Skip to content

Commit 3426631

Browse files
oleksandr-pavlykoleksandr-pavlyk
committed
Add scaffolding to build C++/Python docs
Add sphinx-combined folder that builds combined C++ & Python docs Fixed relative text alignment in docstrings to fix autodoc warnigns Renamed cuda.bench.test_cpp_exception and cuda.bench.test_py_exception functions to start with underscore, signaling that these functions are internal and should not be documented Account for test_cpp_exceptions -> _test_cpp_exception, same for *_py_* Fix cpp_benchmarks, add py_benchmarks 1. Fixed xrefs in docs/sphinx-combined/cpp_benchmarks.md, which is built on top of docs/benchmarks.md Added level-1 heading, and pushed existing headings one level down. 2. Added py_benchmarks.md to document benchmarking of Python scripts. 3. Rearranged entries in index.rst so that overview documents come before API enumeration. Make sure to reset __module__ of reexported symbols to be cuda.bench Enumerate free functions in nvbench:: namespace Tweak to index.rst intro sentence and title Changed title, fixed references, added intro borrowed from README Fix punctuation in one of the itemlist item text Hide TOC from the index page. It is too long and confusing
1 parent 317dc68 commit 3426631

File tree

15 files changed

+890
-16
lines changed

15 files changed

+890
-16
lines changed

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sphinx-combined/_build
2+
sphinx-combined/_doxygen

‎docs/build_combined_docs.sh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
5+
BUILD_DIR="${SCRIPT_DIR}/sphinx-combined/_build"
6+
DOXYGEN_DIR="${SCRIPT_DIR}/sphinx-combined/_doxygen"
7+
8+
mkdir -p "${BUILD_DIR}" "${DOXYGEN_DIR}"
9+
10+
echo "Running Doxygen for combined C++ API..."
11+
(cd "${SCRIPT_DIR}/sphinx-combined" && doxygen Doxyfile)
12+
13+
echo "Building combined Sphinx docs..."
14+
sphinx-build -E -b html "${SCRIPT_DIR}/sphinx-combined" "${BUILD_DIR}"
15+
16+
echo "Combined docs available at ${BUILD_DIR}/index.html"

‎docs/cli_help.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,7 @@
6969

7070
* `--axis <axis specification>`, `-a <axis specification>`
7171
* Override an axis specification.
72-
* See `--help-axis`
73-
for [details on axis specifications](./cli_help_axis.md).
72+
* See `--help-axis` for details on axis specifications.
7473
* Applies to the most recent `--benchmark`, or all benchmarks if specified
7574
before any `--benchmark` arguments.
7675

‎docs/sphinx-combined/Doxyfile‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
PROJECT_NAME = "NVBench"
2+
PROJECT_BRIEF = "C++ NVBench Library"
3+
OUTPUT_DIRECTORY = _doxygen
4+
GENERATE_XML = YES
5+
GENERATE_HTML = NO
6+
GENERATE_LATEX = NO
7+
QUIET = YES
8+
WARN_IF_UNDOCUMENTED = NO
9+
WARN_IF_DOC_ERROR = YES
10+
WARN_LOGFILE = _doxygen/warnings.log
11+
INPUT = ../../nvbench
12+
EXCLUDE = ../../nvbench/cupti_profiler.cxx
13+
EXCLUDE_SYMBOLS = type_strings \
14+
nvbench::detail \
15+
nvbench::internal \
16+
nvbench::tl \
17+
UNUSED \
18+
M_PI \
19+
NVBENCH_UNIQUE_IDENTIFIER_IMPL1 \
20+
NVBENCH_UNIQUE_IDENTIFIER_IMPL2 \
21+
main \
22+
NVBENCH_STATE_EXEC_GUARD \
23+
wrapped_type
24+
FILE_PATTERNS = *.cuh *.cxx *.cu *.h *.hpp
25+
EXTENSION_MAPPING = cuh=C++ cu=C++
26+
RECURSIVE = YES
27+
EXTRACT_ALL = YES
28+
EXTRACT_PRIVATE = YES
29+
EXTRACT_STATIC = YES
30+
JAVADOC_AUTOBRIEF = YES
31+
MULTILINE_CPP_IS_BRIEF = YES
32+
STRIP_FROM_PATH = ../../
33+
ENABLE_PREPROCESSING = YES
34+
MACRO_EXPANSION = YES
35+
EXPAND_ONLY_PREDEF = NO
36+
GENERATE_TAGFILE =
37+
XML_PROGRAMLISTING = NO
38+
PREDEFINED = __device__= \
39+
__host__= \
40+
__global__= \
41+
__forceinline__= \
42+
__shared__= \
43+
__align__(x)= \
44+
__launch_bounds__(x)= \
45+
NVBENCH_HAS_CUDA=1

‎docs/sphinx-combined/_static/nvidia-logo.png‎

126 KB
Loading

‎docs/sphinx-combined/cli_overview.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
CLI Options
2+
===========
3+
4+
Every benchmark created with NVBench supports command-line interface,
5+
with a variety of options.
6+
7+
.. _cli-overview:
8+
9+
.. include:: ../cli_help.md
10+
:parser: myst_parser.sphinx_
11+
12+
.. _cli-overview-axes:
13+
14+
.. include:: ../cli_help_axis.md
15+
:parser: myst_parser.sphinx_

‎docs/sphinx-combined/conf.py‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
import os
2+
3+
project = "NVBench: CUDA Kernel Benchmarking Library"
4+
author = "NVIDIA Corporation"
5+
6+
extensions = [
7+
"breathe",
8+
"sphinx.ext.autodoc",
9+
"sphinx.ext.napoleon",
10+
"sphinx.ext.autosummary",
11+
"myst_parser",
12+
]
13+
14+
templates_path = ["_templates"]
15+
exclude_patterns = ["_build", "_doxygen"]
16+
17+
autosummary_generate = True
18+
autodoc_default_options = {"members": True, "undoc-members": True}
19+
20+
release = "0.2.0"
21+
22+
_here = os.path.abspath(os.path.dirname(__file__))
23+
_doxygen_xml = os.path.join(_here, "_doxygen", "xml")
24+
25+
breathe_projects = {"nvbench": _doxygen_xml}
26+
breathe_default_project = "nvbench"
27+
breathe_domain_by_extension = {"cuh": "cpp", "cxx": "cpp", "cu": "cpp"}
28+
29+
30+
def _patch_breathe_namespace_declarations() -> None:
31+
try:
32+
import breathe.renderer.sphinxrenderer as sphinxrenderer
33+
from docutils import nodes
34+
from sphinx import addnodes
35+
except Exception:
36+
return
37+
38+
original = sphinxrenderer.SphinxRenderer.handle_declaration
39+
40+
def handle_declaration(self, nodeDef, declaration, *args, **kwargs):
41+
is_namespace = getattr(nodeDef, "kind", None) == "namespace"
42+
if not is_namespace:
43+
return original(self, nodeDef, declaration, *args, **kwargs)
44+
45+
name = (declaration or "").strip()
46+
if name.startswith("namespace "):
47+
name = name[len("namespace ") :].strip()
48+
if not name:
49+
name = "<anonymous>"
50+
51+
keyword = addnodes.desc_sig_keyword("namespace", "namespace")
52+
sig_name = addnodes.desc_sig_name(name, name)
53+
return [keyword, nodes.Text(" "), sig_name]
54+
55+
sphinxrenderer.SphinxRenderer.handle_declaration = handle_declaration
56+
57+
58+
def setup(app):
59+
_patch_breathe_namespace_declarations()
60+
61+
62+
######################################################
63+
64+
# -- Options for HTML output -------------------------------------------------
65+
66+
html_theme = "nvidia_sphinx_theme"
67+
68+
html_logo = "_static/nvidia-logo.png"
69+
70+
html_baseurl = (
71+
os.environ.get("NVBENCH_DOCS_BASE_URL", "https://nvidia.github.io/nvbench/").rstrip(
72+
"/"
73+
)
74+
+ "/"
75+
)
76+
77+
html_theme_options = {
78+
"icon_links": [
79+
{
80+
"name": "GitHub",
81+
"url": "https://github.com/NVIDIA/nvbench",
82+
"icon": "fa-brands fa-github",
83+
"type": "fontawesome",
84+
}
85+
],
86+
"navigation_depth": 4,
87+
"show_toc_level": 2,
88+
"navbar_start": ["navbar-logo"],
89+
"navbar_end": ["theme-switcher", "navbar-icon-links"],
90+
"footer_start": ["copyright"],
91+
"footer_end": ["sphinx-version"],
92+
"sidebar_includehidden": True,
93+
"collapse_navigation": False,
94+
# "switcher": {
95+
# "json_url": f"{html_baseurl}nv-versions.json",
96+
# "version_match": release,
97+
# },
98+
}
99+
100+
html_static_path = ["_static"] if os.path.exists("_static") else []
101+
102+
# Images directory
103+
if os.path.exists("img"):
104+
html_static_path.append("img")

‎docs/sphinx-combined/cpp_api.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
NVBench C++ API Reference
2+
=========================
3+
4+
Index
5+
-----
6+
7+
.. doxygenindex::
8+
:project: nvbench
9+
10+
11+
Free Functions
12+
--------------
13+
14+
.. doxygenfunction:: nvbench::make_cuda_stream_view
15+
:project: nvbench
16+
17+
.. doxygenfunction:: nvbench::axis_type_to_string
18+
:project: nvbench
19+
20+
.. doxygenfunction:: nvbench::add_devices_section
21+
:project: nvbench
22+
23+
.. doxygenfunction:: nvbench::range
24+
:project: nvbench
25+
26+
.. doxygenfunction:: nvbench::sleep_kernel
27+
:project: nvbench
28+
29+
.. doxygenfunction:: nvbench::copy_kernel
30+
:project: nvbench
31+
32+
.. doxygenfunction:: nvbench::mod2_kernel
33+
:project: nvbench
34+
35+
.. doxygenfunction:: nvbench::demangle(const std::string &str)
36+
:project: nvbench
37+
38+
.. cpp:function:: template <typename T> std::string nvbench::demangle()
39+
40+
Returns demangled type name.

0 commit comments

Comments
 (0)