diff --git a/docs_sphinx/CMakeLists.txt b/docs_sphinx/CMakeLists.txt index 763a353006..a32333063a 100644 --- a/docs_sphinx/CMakeLists.txt +++ b/docs_sphinx/CMakeLists.txt @@ -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) diff --git a/docs_sphinx/conf.py b/docs_sphinx/conf.py index cf084ebdac..9b82459b76 100644 --- a/docs_sphinx/conf.py +++ b/docs_sphinx/conf.py @@ -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/**", ] diff --git a/docs_sphinx/conf_helpers/build.py b/docs_sphinx/conf_helpers/build.py index d228bf1c53..3b1fa2fc37 100644 --- a/docs_sphinx/conf_helpers/build.py +++ b/docs_sphinx/conf_helpers/build.py @@ -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'
\n{chr(10).join(render(tree))}\n
\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'
\n{chr(10).join(body)}\n
\n' + + _api_index_toctree(("class", "struct", "union")) ) try: (SPHINX_INPUT_ROOT / "class_list.markdown").write_text( diff --git a/docs_sphinx/conf_helpers/stubs.py b/docs_sphinx/conf_helpers/stubs.py index 9bcc6ab5d9..12b2e47304 100644 --- a/docs_sphinx/conf_helpers/stubs.py +++ b/docs_sphinx/conf_helpers/stubs.py @@ -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)") diff --git a/docs_sphinx/conf_helpers/targets.py b/docs_sphinx/conf_helpers/targets.py new file mode 100644 index 0000000000..62eb0173d7 --- /dev/null +++ b/docs_sphinx/conf_helpers/targets.py @@ -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\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)) diff --git a/docs_sphinx/conf_helpers/translate.py b/docs_sphinx/conf_helpers/translate.py index 54c8c83902..47c31a938c 100644 --- a/docs_sphinx/conf_helpers/translate.py +++ b/docs_sphinx/conf_helpers/translate.py @@ -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" diff --git a/docs_sphinx/conf_helpers/xml_render.py b/docs_sphinx/conf_helpers/xml_render.py index 84f92725ce..caaafff43f 100644 --- a/docs_sphinx/conf_helpers/xml_render.py +++ b/docs_sphinx/conf_helpers/xml_render.py @@ -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 diff --git a/docs_sphinx/tests/test_warnings.py b/docs_sphinx/tests/test_warnings.py new file mode 100644 index 0000000000..59df690bf4 --- /dev/null +++ b/docs_sphinx/tests/test_warnings.py @@ -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('', 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('' + ': Note text.') + 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() diff --git a/modules/core/include/opencv2/core/cuda_types.hpp b/modules/core/include/opencv2/core/cuda_types.hpp index fdd1f82c51..e664116d04 100644 --- a/modules/core/include/opencv2/core/cuda_types.hpp +++ b/modules/core/include/opencv2/core/cuda_types.hpp @@ -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 diff --git a/modules/dnn/src/layers/cpu_kernels/fast_attn.cpp b/modules/dnn/src/layers/cpu_kernels/fast_attn.cpp index 4f616d502e..c6a059e92b 100644 --- a/modules/dnn/src/layers/cpu_kernels/fast_attn.cpp +++ b/modules/dnn/src/layers/cpu_kernels/fast_attn.cpp @@ -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 inline v_float32 load_int_mask_as_f32(const T* ptr) { return vx_setall_f32(0.f); } +#endif template