mirror of
https://github.com/opencv/opencv.git
synced 2026-11-21 00:35:35 -06:00
Fix Sphinx API targets, navigation and documentation warnings
This commit is contained in:
@@ -127,14 +127,47 @@ if(NOT DEFINED SPHINX_API_MODULES)
|
||||
message(STATUS "docs_sphinx: discovered API modules: ${SPHINX_API_MODULES}")
|
||||
endif()
|
||||
set(_doxy_input "")
|
||||
set(_doxy_bib "${CMAKE_SOURCE_DIR}/doc/opencv.bib")
|
||||
foreach(_m ${SPHINX_API_MODULES})
|
||||
foreach(_base "${CMAKE_SOURCE_DIR}/modules" "${OPENCV_EXTRA_MODULES_PATH}")
|
||||
if(EXISTS "${_base}/${_m}/include")
|
||||
string(APPEND _doxy_input " ${_base}/${_m}/include")
|
||||
foreach(_docs doc tutorials)
|
||||
if(IS_DIRECTORY "${_base}/${_m}/${_docs}")
|
||||
string(APPEND _doxy_input " ${_base}/${_m}/${_docs}")
|
||||
endif()
|
||||
endforeach()
|
||||
file(GLOB _module_bib "${_base}/${_m}/doc/*.bib")
|
||||
foreach(_bib ${_module_bib})
|
||||
list(APPEND _doxy_bib "${_bib}")
|
||||
endforeach()
|
||||
break()
|
||||
endif()
|
||||
endforeach()
|
||||
endforeach()
|
||||
list(REMOVE_DUPLICATES _doxy_bib)
|
||||
string(JOIN " " _doxy_bib ${_doxy_bib})
|
||||
|
||||
# Universal-intrinsics declarations are generated by these macros. Without
|
||||
# expansion, Doxygen cannot resolve references such as v_setall_s8 or v_abs.
|
||||
file(READ "${CMAKE_SOURCE_DIR}/modules/core/include/opencv2/core/hal/intrin_cpp.hpp"
|
||||
_intrin_header)
|
||||
string(REGEX MATCHALL "#define[ \t]+OPENCV_HAL_IMPL_[A-Za-z0-9_]+"
|
||||
_intrin_macros "${_intrin_header}")
|
||||
list(TRANSFORM _intrin_macros REPLACE "^#define[ \t]+" "")
|
||||
string(JOIN " " _intrin_macros ${_intrin_macros})
|
||||
|
||||
# Snippets use both source-relative and repository-prefixed paths. Stage only
|
||||
# the two source trees, rather than recursively searching their parent folder.
|
||||
set(_sphinx_example_roots "${CMAKE_CURRENT_BINARY_DIR}/example_roots")
|
||||
file(MAKE_DIRECTORY "${_sphinx_example_roots}")
|
||||
file(CREATE_LINK "${CMAKE_SOURCE_DIR}" "${_sphinx_example_roots}/opencv"
|
||||
SYMBOLIC COPY_ON_ERROR)
|
||||
if(OPENCV_EXTRA_MODULES_PATH)
|
||||
get_filename_component(_contrib_source "${OPENCV_EXTRA_MODULES_PATH}/.." ABSOLUTE)
|
||||
file(CREATE_LINK "${_contrib_source}" "${_sphinx_example_roots}/opencv_contrib"
|
||||
SYMBOLIC COPY_ON_ERROR)
|
||||
endif()
|
||||
|
||||
if(EXISTS "${_LEGACY_DOXYFILE}")
|
||||
set(_SPHINX_DOXYFILE "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-xml")
|
||||
@@ -152,12 +185,17 @@ if(EXISTS "${_LEGACY_DOXYFILE}")
|
||||
"INCLUDE_GRAPH = NO\n"
|
||||
"INCLUDED_BY_GRAPH = NO\n"
|
||||
"DIRECTORY_GRAPH = NO\n"
|
||||
"INPUT =${_doxy_input}\n"
|
||||
# Keep tutorial/page anchors from the legacy input, in addition to APIs for
|
||||
# optional modules. A headers-only input leaves their @ref targets missing.
|
||||
"INPUT +=${_doxy_input}\n"
|
||||
"CITE_BIB_FILES = ${_doxy_bib}\n"
|
||||
"EXAMPLE_PATH += ${CMAKE_SOURCE_DIR} ${OPENCV_EXTRA_MODULES_PATH} ${_sphinx_example_roots}\n"
|
||||
"RECURSIVE = YES\n"
|
||||
"EXCLUDE_SYMBOLS = cv::DataType<*> int void CV__* T __CV* cv::gapi::detail*\n"
|
||||
"MACRO_EXPANSION = YES\n"
|
||||
"EXPAND_ONLY_PREDEF = YES\n"
|
||||
"PREDEFINED += __device__= __host__= __forceinline__= __global__= __constant__= __shared__= __restrict__=\n"
|
||||
"EXPAND_AS_DEFINED += ${_intrin_macros}\n"
|
||||
"PREDEFINED += __device__= __host__= __forceinline__= __global__= __constant__= __shared__= __restrict__= CV_FORMAT_PRINTF(fmt,params)=\n"
|
||||
)
|
||||
find_program(DOXYGEN_EXE NAMES doxygen)
|
||||
if(DOXYGEN_EXE)
|
||||
|
||||
@@ -84,7 +84,6 @@ if API_MODULES:
|
||||
|
||||
exclude_patterns = [
|
||||
"**/Thumbs.db", "**/.DS_Store", "**/_old/**",
|
||||
"tutorials/core/how_to_use_OpenCV_parallel_for_/**",
|
||||
"tutorials/introduction/load_save_image/**",
|
||||
"tutorials/app/_old/**",
|
||||
]
|
||||
|
||||
@@ -411,6 +411,16 @@ def _esc(s: str) -> str:
|
||||
return (s or "").replace("&", "&").replace("<", "<").replace(">", ">")
|
||||
|
||||
|
||||
def _api_index_toctree(prefixes) -> str:
|
||||
"""Include every generated view, including nested types and redirects."""
|
||||
pages = sorted(
|
||||
p.relative_to(SPHINX_INPUT_ROOT).with_suffix("").as_posix()
|
||||
for folder in ("main_modules", "extra_modules")
|
||||
for p in (SPHINX_INPUT_ROOT / folder).glob("*.md")
|
||||
if p.name.startswith(prefixes))
|
||||
return "\n```{toctree}\n:hidden:\n:maxdepth: 1\n\n" + "\n".join(pages) + "\n```\n"
|
||||
|
||||
|
||||
def _write_namespace_list_index() -> None:
|
||||
"""Generate `namespace_list.markdown` — local analog of Doxygen's
|
||||
namespaces.html (the header "Namespaces" target).
|
||||
@@ -454,6 +464,7 @@ def _write_namespace_list_index() -> None:
|
||||
"# Namespace List\n\n"
|
||||
"Here is a list of all documented namespaces with brief descriptions.\n\n"
|
||||
f'<div class="ocv-namespace-list">\n{chr(10).join(render(tree))}\n</div>\n'
|
||||
+ _api_index_toctree(("namespace_",))
|
||||
)
|
||||
try:
|
||||
(SPHINX_INPUT_ROOT / "namespace_list.markdown").write_text(
|
||||
@@ -501,6 +512,7 @@ def _write_class_list_index() -> None:
|
||||
"# Class List\n\n"
|
||||
"Here are the classes, structs and unions with brief descriptions.\n\n"
|
||||
f'<div class="ocv-class-list-wrap">\n{chr(10).join(body)}\n</div>\n'
|
||||
+ _api_index_toctree(("class", "struct", "union"))
|
||||
)
|
||||
try:
|
||||
(SPHINX_INPUT_ROOT / "class_list.markdown").write_text(
|
||||
|
||||
@@ -844,16 +844,19 @@ def _write_namespace_stub(ns: dict, out_dir: pathlib.Path,
|
||||
spec = m["name"]
|
||||
else:
|
||||
spec = qualified
|
||||
rendered.append((spec, directive))
|
||||
rendered.append((spec, directive, m['id']))
|
||||
if not rendered:
|
||||
continue
|
||||
lines.append(f"## {_MEMBER_DETAIL_SECTION[section_title]}")
|
||||
lines.append("")
|
||||
for spec, dname in rendered:
|
||||
for spec, dname, member_id in rendered:
|
||||
short = spec.split("(")[0].split("::")[-1]
|
||||
suffix = "()" if dname == "doxygenfunction" else ""
|
||||
lines += [f"### {short}{suffix}", "",
|
||||
f"```{{{dname}}} {spec}", ":project: opencv", "```", ""]
|
||||
# The group/class detail owns the C++ declaration. Namespace pages
|
||||
# repeat its documentation with a local target, without registering
|
||||
# the same Breathe targets a second time.
|
||||
lines += [f"({member_id})=", f"### {short}{suffix}", "",
|
||||
f"```{{{dname}}} {spec}", ":project: opencv", ":no-link:", "```", ""]
|
||||
|
||||
_stub_write(out_dir / fname, "\n".join(lines) + "\n")
|
||||
return anchor, fname
|
||||
@@ -1925,6 +1928,7 @@ def _write_class_stub(cls: dict, out_dir: pathlib.Path,
|
||||
"",
|
||||
f"```{{{_directive}}} {qualified}",
|
||||
":project: opencv",
|
||||
":no-link:",
|
||||
"```",
|
||||
"",
|
||||
]
|
||||
@@ -2689,6 +2693,11 @@ def _generate_api_stubs(modules, xml_dir, out_dir,
|
||||
# Hidden toctree drives nav/sidebar; the visible list shows "folder. Title".
|
||||
root_lines += ["```{toctree}", ":hidden:", ":maxdepth: 1", ""]
|
||||
root_lines += [stem for _m, stem, _t in module_rows]
|
||||
# Optional API groups still need a navigation parent even when they are
|
||||
# intentionally omitted from the visible module directory listing.
|
||||
root_lines += [tree["name"] for tree in trees
|
||||
if tree["name"] not in {stem for _m, stem, _t in module_rows}
|
||||
and tree is not _gapi_tree]
|
||||
root_lines += ["```", ""]
|
||||
for _m, stem, title in module_rows:
|
||||
root_lines.append(f"- {_m}. [{title}]({stem}.md)")
|
||||
|
||||
74
docs_sphinx/conf_helpers/targets.py
Normal file
74
docs_sphinx/conf_helpers/targets.py
Normal file
@@ -0,0 +1,74 @@
|
||||
# This file is part of OpenCV project.
|
||||
# It is subject to the license terms in the LICENSE file found in the top-level directory
|
||||
# of this distribution and at http://opencv.org/license.html.
|
||||
|
||||
"""Keep repeated API documentation's fragment targets local to each page."""
|
||||
from functools import lru_cache
|
||||
import html
|
||||
import re
|
||||
|
||||
from .state import SPHINX_INPUT_ROOT
|
||||
|
||||
_LABEL = re.compile(r"^\(([^\n]+)\)=\s*$", re.MULTILINE)
|
||||
_HEADING_LABEL = re.compile(r"\{#([\w-]+)\}")
|
||||
|
||||
|
||||
@lru_cache(maxsize=1)
|
||||
def _label_owners():
|
||||
# All workers use the same sorted input, independent of read order. Prefer
|
||||
# group/class pages over namespace summaries for a global reference target.
|
||||
owners = {}
|
||||
paths = [p for folder in ("main_modules", "extra_modules")
|
||||
for p in (SPHINX_INPUT_ROOT / folder).glob("*.md")]
|
||||
from .translate import _apply_outside_code
|
||||
for path in sorted(paths, key=lambda p: (p.name.startswith("namespace_"), str(p))):
|
||||
docname = path.relative_to(SPHINX_INPUT_ROOT).with_suffix("").as_posix()
|
||||
text = path.read_text(encoding="utf-8")
|
||||
labels = []
|
||||
def collect(chunk):
|
||||
labels.extend(m.group(1) for m in _LABEL.finditer(chunk))
|
||||
labels.extend(_HEADING_LABEL.findall(chunk))
|
||||
return chunk
|
||||
_apply_outside_code(text, collect)
|
||||
for label in labels:
|
||||
owners.setdefault(label.lower(), docname)
|
||||
return owners
|
||||
|
||||
|
||||
def localize_api_labels(text, docname):
|
||||
"""Register a label globally once; retain duplicate pages' HTML fragments.
|
||||
|
||||
A member can appear in a group, namespace and class view. Re-registering
|
||||
its MyST label makes the global target depend on parallel read order.
|
||||
Links to the other views still need their page-local fragment IDs.
|
||||
"""
|
||||
from docutils import nodes
|
||||
owners = _label_owners()
|
||||
seen = set()
|
||||
local_labels = {}
|
||||
|
||||
def replace(match):
|
||||
label = match.group(1)
|
||||
key = label.lower()
|
||||
if key in seen:
|
||||
return ""
|
||||
seen.add(key)
|
||||
if owners.get(key, docname) == docname:
|
||||
return match.group(0)
|
||||
scoped = f"{docname}:{label}"
|
||||
local_labels[key] = scoped
|
||||
target = nodes.make_id(label)
|
||||
return f'({scoped})=\n<a id="{html.escape(target, quote=True)}"></a>\n'
|
||||
|
||||
# Code samples can contain label-like syntax and must remain untouched.
|
||||
from .translate import _apply_outside_code
|
||||
text = _apply_outside_code(text, lambda chunk: _LABEL.sub(replace, chunk))
|
||||
|
||||
def local_link(match):
|
||||
label = match.group(1)
|
||||
return "#" + local_labels.get(label.lower(), label)
|
||||
|
||||
# A bare #label would otherwise resolve to the canonical page's global
|
||||
# label. Use the scoped label for this view's own summary/detail links.
|
||||
return _apply_outside_code(
|
||||
text, lambda chunk: re.sub(r"(?<=\]\()#([^\s)]+)(?=\))", local_link, chunk))
|
||||
@@ -459,7 +459,7 @@ def _translate(text: str, docname: str | None = None) -> str:
|
||||
i += 1
|
||||
return l[i:]
|
||||
body = "\n".join(_dedent(l) for l in lines).strip()
|
||||
block = f":::{{{kind}}}\n{body}\n:::"
|
||||
block = f":::{{{kind}}}\n\n{body}\n:::"
|
||||
if indent:
|
||||
block = "\n".join((indent + ln) if ln.strip() else ln
|
||||
for ln in block.split("\n"))
|
||||
@@ -1558,6 +1558,9 @@ def _source_read(app, docname, source):
|
||||
if API_MODULES and "api_root" in _ANCHOR_TO_DOC:
|
||||
text = text.rstrip() + "\n\n- @subpage api_root\n"
|
||||
out = _translate(text, docname)
|
||||
if docname.startswith(("main_modules/", "extra_modules/")):
|
||||
from .targets import localize_api_labels
|
||||
out = localize_api_labels(out, docname)
|
||||
# Mark unreferenced tutorial pages :orphan: (skip master/front-matter/referenced).
|
||||
if (docname.startswith(_TUTORIAL_PREFIXES)
|
||||
and docname != "tutorials/tutorials"
|
||||
|
||||
@@ -604,7 +604,7 @@ def _doxygen_desc_to_md(el, h_level: int = 3) -> str:
|
||||
admon = _ADMON_BY_KIND.get(kind)
|
||||
body = "\n\n".join(_blocks(sub, level))
|
||||
if admon:
|
||||
result.append(f":::{{{admon}}}\n{body}\n:::")
|
||||
result.append(f":::{{{admon}}}\n\n{body}\n:::")
|
||||
elif body:
|
||||
result.append(body)
|
||||
elif t == "xrefsect":
|
||||
@@ -731,7 +731,7 @@ def _doxygen_desc_to_md(el, h_level: int = 3) -> str:
|
||||
i += 1
|
||||
body = "\n\n".join(b for b in bodies if b)
|
||||
if admon and body:
|
||||
result.append(f":::{{{admon}}}\n{body}\n:::")
|
||||
result.append(f":::{{{admon}}}\n\n{body}\n:::")
|
||||
elif body:
|
||||
result.append(body)
|
||||
continue
|
||||
|
||||
86
docs_sphinx/tests/test_warnings.py
Normal file
86
docs_sphinx/tests/test_warnings.py
Normal file
@@ -0,0 +1,86 @@
|
||||
# This file is part of OpenCV project.
|
||||
# It is subject to the license terms in the LICENSE file found in the top-level directory
|
||||
# of this distribution and at http://opencv.org/license.html.
|
||||
|
||||
"""Run with the docs requirements: python -m unittest discover -s docs_sphinx/tests."""
|
||||
import io
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
from conf_helpers import targets, translate, xml_render
|
||||
|
||||
|
||||
class WarningTests(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.temp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.temp.cleanup)
|
||||
self.root = pathlib.Path(self.temp.name)
|
||||
self.root_patch = patch.object(targets, "SPHINX_INPUT_ROOT", self.root)
|
||||
self.root_patch.start()
|
||||
self.addCleanup(self.root_patch.stop)
|
||||
targets._label_owners.cache_clear()
|
||||
self.addCleanup(targets._label_owners.cache_clear)
|
||||
|
||||
def write(self, docname, text):
|
||||
path = self.root / (docname + ".md")
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(text, encoding="utf-8")
|
||||
|
||||
def test_group_owns_repeated_namespace_label(self):
|
||||
text = "(Member_ID)=\n### Member\n"
|
||||
self.write("main_modules/group", text)
|
||||
self.write("extra_modules/namespace_cv", text)
|
||||
self.assertEqual(targets.localize_api_labels(text, "main_modules/group"), text)
|
||||
duplicate = targets.localize_api_labels(text, "extra_modules/namespace_cv")
|
||||
self.assertIn('<a id="member-id"></a>', duplicate)
|
||||
self.assertNotIn("(Member_ID)=", duplicate)
|
||||
|
||||
def test_label_examples_do_not_claim_targets(self):
|
||||
text = "```text\n(member)=\n```\n"
|
||||
self.write("main_modules/a_example", text)
|
||||
self.write("main_modules/z_actual", "(member)=\n# Member\n")
|
||||
self.assertEqual(targets.localize_api_labels(text, "main_modules/a_example"), text)
|
||||
self.assertEqual(targets._label_owners()["member"], "main_modules/z_actual")
|
||||
|
||||
def test_note_body_is_separated_from_options(self):
|
||||
text = translate._translate("@note : This is note text.\n", "tutorials/test")
|
||||
self.assertIn(":::{note}\n\n: This is note text.", text)
|
||||
# Exercise the XML block renderer with a note nested in a paragraph.
|
||||
node = ET.fromstring('<detaileddescription><para><simplesect kind="note">'
|
||||
'<para>: Note text.</para></simplesect></para></detaileddescription>')
|
||||
text = xml_render._doxygen_desc_to_md(node, 2)
|
||||
self.assertIn(":::{note}\n\n: Note text.", text)
|
||||
|
||||
def test_sphinx_keeps_global_and_page_local_links(self):
|
||||
from sphinx.application import Sphinx
|
||||
self.write("index", "# API\n\n```{toctree}\n\nmain_modules/group\n"
|
||||
"extra_modules/namespace_cv\n```\n")
|
||||
for docname in ("main_modules/group", "extra_modules/namespace_cv"):
|
||||
self.write(docname, "# API view\n\n(Member_ID)=\n## Member\n\n"
|
||||
'[Local member](#Member_ID)\n')
|
||||
(self.root / "conf.py").write_text(
|
||||
"extensions = ['myst_parser']\nmaster_doc = 'index'\n"
|
||||
"source_suffix = {'.md': 'markdown'}\n", encoding="utf-8")
|
||||
warnings = io.StringIO()
|
||||
app = Sphinx(str(self.root), str(self.root), str(self.root / "_html"),
|
||||
str(self.root / "_doctrees"), "html", status=io.StringIO(),
|
||||
warning=warnings, freshenv=True)
|
||||
def source_read(app, docname, source):
|
||||
source[0] = targets.localize_api_labels(source[0], docname)
|
||||
app.connect("source-read", source_read)
|
||||
app.build(force_all=True)
|
||||
self.assertEqual(warnings.getvalue(), "")
|
||||
self.assertEqual(app.env.domains["std"].labels["member_id"][0], "main_modules/group")
|
||||
html = (self.root / "_html/extra_modules/namespace_cv.html").read_text()
|
||||
self.assertIn('id="member-id"', html)
|
||||
self.assertIn('href="#extra-modules-namespace-cv-member-id"', html)
|
||||
self.assertIn('id="extra-modules-namespace-cv-member-id"', html)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -50,7 +50,7 @@
|
||||
#if defined(__OPENCV_BUILD) && defined(__clang__)
|
||||
#pragma clang diagnostic ignored "-Winconsistent-missing-override"
|
||||
#endif
|
||||
#if defined(__OPENCV_BUILD) && defined(__GNUC__)
|
||||
#if defined(__OPENCV_BUILD) && defined(__GNUC__) && !defined(__clang__)
|
||||
#pragma GCC diagnostic ignored "-Wsuggest-override"
|
||||
#endif
|
||||
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
|
||||
namespace cv { namespace dnn {
|
||||
|
||||
#if (CV_SIMD || CV_SIMD_SCALABLE)
|
||||
static inline v_float32 load_int_mask_as_f32(const int32_t* ptr) {
|
||||
v_int32 v = vx_load(ptr);
|
||||
return v_reinterpret_as_f32(v_ne(v, vx_setall_s32(0)));
|
||||
@@ -31,6 +32,7 @@ template<typename T>
|
||||
inline v_float32 load_int_mask_as_f32(const T* ptr) {
|
||||
return vx_setall_f32(0.f);
|
||||
}
|
||||
#endif
|
||||
|
||||
|
||||
template <typename MaskT>
|
||||
|
||||
Reference in New Issue
Block a user