Add scaffolding to build C++/Python docs

docs/.gitignore

@@ -0,0 +1,2 @@
+sphinx-combined/_build
+sphinx-combined/_doxygen

docs/build_combined_docs.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BUILD_DIR="${SCRIPT_DIR}/sphinx-combined/_build"
+DOXYGEN_DIR="${SCRIPT_DIR}/sphinx-combined/_doxygen"
+
+mkdir -p "${BUILD_DIR}" "${DOXYGEN_DIR}"
+
+echo "Running Doxygen for combined C++ API..."
+(cd "${SCRIPT_DIR}/sphinx-combined" && doxygen Doxyfile)
+
+echo "Building combined Sphinx docs..."
+sphinx-build -E -b html "${SCRIPT_DIR}/sphinx-combined" "${BUILD_DIR}"
+
+echo "Combined docs available at ${BUILD_DIR}/index.html"

docs/cli_help.md

@@ -69,8 +69,7 @@
 
 * `--axis <axis specification>`, `-a <axis specification>`
   * Override an axis specification.
-  * See `--help-axis`
-    for [details on axis specifications](./cli_help_axis.md).
+  * See `--help-axis` for details on axis specifications.
   * Applies to the most recent `--benchmark`, or all benchmarks if specified
     before any `--benchmark` arguments.
 

docs/sphinx-combined/Doxyfile

@@ -0,0 +1,45 @@
+PROJECT_NAME           = "NVBench"
+PROJECT_BRIEF          = "C++ NVBench Library"
+OUTPUT_DIRECTORY       = _doxygen
+GENERATE_XML           = YES
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+QUIET                  = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_LOGFILE           = _doxygen/warnings.log
+INPUT                  = ../../nvbench
+EXCLUDE                = ../../nvbench/cupti_profiler.cxx
+EXCLUDE_SYMBOLS        = type_strings \
+                         nvbench::detail \
+                         nvbench::internal \
+                         nvbench::tl \
+                         UNUSED \
+                         M_PI \
+                         NVBENCH_UNIQUE_IDENTIFIER_IMPL1 \
+                         NVBENCH_UNIQUE_IDENTIFIER_IMPL2 \
+                         main \
+                         NVBENCH_STATE_EXEC_GUARD \
+                         wrapped_type
+FILE_PATTERNS          = *.cuh *.cxx *.cu *.h *.hpp
+EXTENSION_MAPPING      = cuh=C++ cu=C++
+RECURSIVE              = YES
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+JAVADOC_AUTOBRIEF      = YES
+MULTILINE_CPP_IS_BRIEF = YES
+STRIP_FROM_PATH        = ../../
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+GENERATE_TAGFILE       =
+XML_PROGRAMLISTING    = NO
+PREDEFINED             = __device__= \
+                         __host__= \
+                         __global__= \
+                         __forceinline__= \
+                         __shared__= \
+                         __align__(x)= \
+                         __launch_bounds__(x)= \
+                         NVBENCH_HAS_CUDA=1

docs/sphinx-combined/cli_overview.rst

@@ -0,0 +1,12 @@
+CLI Options
+===========
+
+Every benchmark created with NVBench supports command-line interface,
+with a variety of options.
+
+.. include:: ../cli_help.md
+   :parser: myst_parser.sphinx_
+
+
+.. include:: ../cli_help_axis.md
+   :parser: myst_parser.sphinx_

docs/sphinx-combined/conf.py

@@ -0,0 +1,104 @@
+import os
+
+project = "NVBench API"
+author = "NVIDIA Corporation"
+
+extensions = [
+    "breathe",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "myst_parser",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "_doxygen"]
+
+autosummary_generate = True
+autodoc_default_options = {"members": True, "undoc-members": True}
+
+release = "0.2.0"
+
+_here = os.path.abspath(os.path.dirname(__file__))
+_doxygen_xml = os.path.join(_here, "_doxygen", "xml")
+
+breathe_projects = {"nvbench": _doxygen_xml}
+breathe_default_project = "nvbench"
+breathe_domain_by_extension = {"cuh": "cpp", "cxx": "cpp", "cu": "cpp"}
+
+
+def _patch_breathe_namespace_declarations() -> None:
+    try:
+        import breathe.renderer.sphinxrenderer as sphinxrenderer
+        from docutils import nodes
+        from sphinx import addnodes
+    except Exception:
+        return
+
+    original = sphinxrenderer.SphinxRenderer.handle_declaration
+
+    def handle_declaration(self, nodeDef, declaration, *args, **kwargs):
+        is_namespace = getattr(nodeDef, "kind", None) == "namespace"
+        if not is_namespace:
+            return original(self, nodeDef, declaration, *args, **kwargs)
+
+        name = (declaration or "").strip()
+        if name.startswith("namespace "):
+            name = name[len("namespace ") :].strip()
+        if not name:
+            name = "<anonymous>"
+
+        keyword = addnodes.desc_sig_keyword("namespace", "namespace")
+        sig_name = addnodes.desc_sig_name(name, name)
+        return [keyword, nodes.Text(" "), sig_name]
+
+    sphinxrenderer.SphinxRenderer.handle_declaration = handle_declaration
+
+
+def setup(app):
+    _patch_breathe_namespace_declarations()
+
+
+######################################################
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "nvidia_sphinx_theme"
+
+html_logo = "_static/nvidia-logo.png"
+
+html_baseurl = (
+    os.environ.get("NVBENCH_DOCS_BASE_URL", "https://nvidia.github.io/nvbench/").rstrip(
+        "/"
+    )
+    + "/"
+)
+
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/NVIDIA/nvbench",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        }
+    ],
+    "navigation_depth": 4,
+    "show_toc_level": 2,
+    "navbar_start": ["navbar-logo"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    "footer_start": ["copyright"],
+    "footer_end": ["sphinx-version"],
+    "sidebar_includehidden": True,
+    "collapse_navigation": False,
+    #    "switcher": {
+    #        "json_url": f"{html_baseurl}nv-versions.json",
+    #        "version_match": release,
+    #    },
+}
+
+html_static_path = ["_static"] if os.path.exists("_static") else []
+
+# Images directory
+if os.path.exists("img"):
+    html_static_path.append("img")

docs/sphinx-combined/cpp_api.rst

@@ -0,0 +1,40 @@
+NVBench C++ API Reference
+=========================
+
+Index
+-----
+
+.. doxygenindex::
+   :project: nvbench
+
+
+Free Functions
+--------------
+
+.. doxygenfunction:: nvbench::make_cuda_stream_view
+   :project: nvbench
+
+.. doxygenfunction:: nvbench::axis_type_to_string
+   :project: nvbench
+
+.. doxygenfunction:: nvbench::add_devices_section
+   :project: nvbench
+
+.. doxygenfunction:: nvbench::range
+   :project: nvbench
+
+.. doxygenfunction:: nvbench::sleep_kernel
+   :project: nvbench
+
+.. doxygenfunction:: nvbench::copy_kernel
+   :project: nvbench
+
+.. doxygenfunction:: nvbench::mod2_kernel
+   :project: nvbench
+
+.. doxygenfunction:: nvbench::demangle(const std::string &str)
+   :project: nvbench
+
+.. cpp:function:: template <typename T> std::string nvbench::demangle()
+
+   Returns demangled type name.