Fix Sphinx API targets, navigation and documentation warnings

This commit is contained in:
Abhishek gola
2026-11-16 20:13:32 +05:30
parent 5d112831b5
commit 315ddafc6c
10 changed files with 234 additions and 11 deletions

View File

@@ -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)

View File

@@ -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/**",
]

View File

@@ -411,6 +411,16 @@ def _esc(s: str) -> str:
return (s or "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
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(

View File

@@ -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)")

View 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))

View File

@@ -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"

View File

@@ -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

View 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()

View File

@@ -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

View File

@@ -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>