Add C++ API reference to Sphinx docs

.gitignore

@@ -74,6 +74,7 @@ doxygen_check/
 
 ## Doxygen
 cpp/html
+cpp/xml
 cpp/Doxyfile
 
 # clang tooling

conda/environments/all_cuda-129_arch-aarch64.yaml

@@ -5,6 +5,7 @@ channels:
 - rapidsai
 - conda-forge
 dependencies:
+- breathe
 - c-compiler
 - ccache
 - certifi

conda/environments/all_cuda-129_arch-x86_64.yaml

@@ -5,6 +5,7 @@ channels:
 - rapidsai
 - conda-forge
 dependencies:
+- breathe
 - c-compiler
 - ccache
 - certifi

conda/environments/all_cuda-133_arch-aarch64.yaml

@@ -5,6 +5,7 @@ channels:
 - rapidsai
 - conda-forge
 dependencies:
+- breathe
 - c-compiler
 - ccache
 - certifi

conda/environments/all_cuda-133_arch-x86_64.yaml

@@ -5,6 +5,7 @@ channels:
 - rapidsai
 - conda-forge
 dependencies:
+- breathe
 - c-compiler
 - ccache
 - certifi

cpp/Doxyfile.in

@@ -2011,7 +2011,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

dependencies.yaml

@@ -509,6 +509,7 @@ dependencies:
     common:
       - output_types: [conda, requirements]
         packages:
+          - breathe
           - graphviz
           - ipython
           - ipykernel

docs/source/conf.py

@@ -16,9 +16,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import datetime
+import glob
 import os
 import sys
 import textwrap
+import xml.etree.ElementTree as ET
 
 from packaging.version import Version
 
@@ -43,6 +45,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "breathe",
     "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
@@ -58,6 +61,55 @@
     "sphinx_design",
 ]
 
+breathe_projects = {
+    "cuml": os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "../../cpp/xml")
+    )
+}
+breathe_default_project = "cuml"
+
+
+def clean_doxygen_xml(path: str) -> None:
+    # Doxygen 1.9.1 emits concepts and instantiations that Sphinx cannot parse,
+    # duplicates enum IDs, and gives TSNE_INIT::PCA the same C++ target as ML::PCA.
+    for filename in glob.glob(os.path.join(path, "*.xml")):
+        tree = ET.parse(filename)
+        changed = False
+        for section in tree.findall(".//sectiondef"):
+            for member in list(section.findall("memberdef")):
+                type_node = member.find("type")
+                type_text = (
+                    "".join(type_node.itertext())
+                    if type_node is not None
+                    else ""
+                )
+                if type_text in {"concept", "template void"}:
+                    section.remove(member)
+                    changed = True
+                    continue
+
+                if member.get("kind") != "enum":
+                    continue
+                member_id = member.get("id", "")
+                for value in list(member.findall("enumvalue")):
+                    if (
+                        member.findtext("name") == "TSNE_INIT"
+                        and value.findtext("name") == "PCA"
+                    ):
+                        member.remove(value)
+                        changed = True
+                    elif not value.get("id", "").startswith(member_id):
+                        value.set(
+                            "id", f"{member_id}_{value.findtext('name')}"
+                        )
+                        changed = True
+        if changed:
+            tree.write(filename, encoding="UTF-8", xml_declaration=True)
+
+
+for project_path in breathe_projects.values():
+    clean_doxygen_xml(project_path)
+
 ipython_mplbackend = "str"
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/cpp/genetic.rst

@@ -0,0 +1,5 @@
+cuml::genetic Namespace
+=======================
+
+.. doxygennamespace:: cuml::genetic
+   :members:

docs/source/cpp/index.rst

@@ -0,0 +1,11 @@
+C++ API
+=======
+
+This section documents the C++ API for cuML, also called ``libcuml``.
+
+.. toctree::
+   :maxdepth: 1
+
+   ml
+   mlcommon
+   genetic

docs/source/cpp/ml.rst

@@ -0,0 +1,5 @@
+ML Namespace
+============
+
+.. doxygennamespace:: ML
+   :members:

docs/source/cpp/mlcommon.rst

@@ -0,0 +1,5 @@
+MLCommon Namespace
+==================
+
+.. doxygennamespace:: MLCommon
+   :members:

docs/source/index.rst

@@ -78,4 +78,5 @@ Community & Support
    user_guide.rst
    Zero Code Change Acceleration <cuml-accel/index.rst>
    api/index
+   cpp/index
    cuml_blogs.rst