Merge pull request #165 from leofang/new_docs

Prepare docs for sub-packages

cuda_bindings/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -j auto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build/html/${SPHINX_CUDA_BINDINGS_VER}
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -b help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

cuda_bindings/docs/README.md

@@ -0,0 +1,11 @@
+# Build the documentation
+
+1. Install the `cuda-bindings` package of the version that we need to document.
+2. Ensure the version is included in the [`versions.json`](./versions.json).
+3. Build the docs with `./build_docs.sh`.
+4. The html artifacts should be available under both `./build/html/latest` and `./build/html/<version>`.
+
+Alternatively, we can build all the docs at once by running [`cuda_python/docs/build_all_docs.sh`](../../cuda_python/docs/build_all_docs.sh).
+
+To publish the docs with the built version, it is important to note that the html files of older versions
+should be kept intact, in order for the version selection (through `versions.json`) to work.

cuda_bindings/docs/build_docs.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+set -ex
+
+# SPHINX_CUDA_BINDINGS_VER is used to create a subdir under build/html
+# (the Makefile file for sphinx-build also honors it if defined)
+if [[ -z "${SPHINX_CUDA_BINDINGS_VER}" ]]; then
+    export SPHINX_CUDA_BINDINGS_VER=$(python -c "from importlib.metadata import version; print(version('cuda-python'))" \
+                                      | awk -F'+' '{print $1}')
+fi
+
+# build the docs (in parallel)
+SPHINXOPTS="-j 4" make html
+
+# for debugging/developing (conf.py), please comment out the above line and
+# use the line below instead, as we must build in serial to avoid getting
+# obsecure Sphinx errors
+#SPHINXOPTS="-v" make html
+
+# to support version dropdown menu
+cp ./versions.json build/html
+
+# to have a redirection page (to the latest docs)
+cp source/_templates/main.html build/html/index.html
+
+# ensure that the latest docs is the one we built
+cp -r build/html/${SPHINX_CUDA_BINDINGS_VER} build/html/latest
+
+# ensure that the Sphinx reference uses the latest docs
+cp build/html/latest/objects.inv build/html

cuda_bindings/docs/source/_static/javascripts/version_dropdown.js

@@ -0,0 +1,58 @@
+function change_current_version(event) {
+  event.preventDefault();
+
+  var selectedVersion = event.target.textContent;
+  var currentVersion = document.getElementById('currentVersion');
+
+  // need to update both the on-screen state and the internal (persistent) storage
+  currentVersion.textContent = selectedVersion;
+  sessionStorage.setItem("currentVersion", selectedVersion);
+
+  // Navigate to the clicked URL
+  window.location.href = event.target.href;
+}
+
+
+function add_version_dropdown(jsonLoc, targetLoc, currentVersion) {
+  var otherVersionsDiv = document.getElementById('otherVersions');
+
+  fetch(jsonLoc)
+    .then(function(response) {
+      return response.json();
+    })
+    .then(function(data) {
+      var versions = data;
+
+      if (Object.keys(versions).length >= 1) {
+        var dlElement = document.createElement('dl');
+        var dtElement = document.createElement('dt');
+        dtElement.textContent = 'Versions';
+        dlElement.appendChild(dtElement);
+
+        for (var ver in versions) {
+          var url = versions[ver];
+          var ddElement = document.createElement('dd');
+          var aElement = document.createElement('a');
+          aElement.setAttribute('href', targetLoc + url);
+          aElement.textContent = ver;
+
+          if (ver === currentVersion) {
+            var strongElement = document.createElement('strong');
+            strongElement.appendChild(aElement);
+            aElement = strongElement;
+          }
+
+          ddElement.appendChild(aElement);
+          // Attach event listeners to version links
+          ddElement.addEventListener('click', change_current_version);
+          dlElement.appendChild(ddElement);
+        }
+
+        otherVersionsDiv.innerHTML = '';
+        otherVersionsDiv.appendChild(dlElement);
+      }
+    })
+    .catch(function(error) {
+      console.error('Error fetching version.json:', error);
+    });
+}

cuda_bindings/docs/source/_templates/main.html

@@ -0,0 +1,13 @@
+<!DOCTYPE HTML>
+<html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta http-equiv="refresh" content="0; url=latest/" />
+        <link rel="canonical" href="latest/" />
+    </head>
+    <body>
+        <p>If this page does not refresh automatically, then please direct your browser to
+            <a href="latest/">our latest docs</a>.
+        </p>
+    </body>
+</html>

cuda_bindings/docs/source/_templates/sidebar/variant-selector.html

@@ -0,0 +1,24 @@
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> cuda-bindings</span>
+    v: <span id="currentVersion">{{ version }}</span>
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions" id="otherVersions">
+    <hr/>
+  </div>
+</div>
+
+<script src="{{ pathto('_static/javascripts/version_dropdown.js', 1) }}"></script>
+<script>
+  var jsonLoc = "{{ pathto('../versions.json', 1) }}";
+  var targetLoc = "{{ pathto('../', 1) }}";
+  // note: sessionStorage is an html5 construct
+  var currentVersion = sessionStorage.getItem("currentVersion") || "";
+  if (!currentVersion) {
+    currentVersion = document.getElementById('currentVersion').textContent;  // default
+  } else {
+    document.getElementById('currentVersion').textContent = currentVersion;  // update
+  }
+  add_version_dropdown(jsonLoc, targetLoc, currentVersion);
+</script>

cuda_bindings/docs/source/conf.py

@@ -0,0 +1,86 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'cuda.bindings'
+copyright = '2021-2024, NVIDIA'
+author = 'NVIDIA'
+
+# The full version, including alpha/beta/rc tags
+release = os.environ["SPHINX_CUDA_BINDINGS_VER"]
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+	'sphinx.ext.autodoc',
+	'sphinx.ext.napoleon',
+	'myst_nb',
+	'enum_tools.autoenum'
+]
+
+jupyter_execute_notebooks = "force"
+numfig=True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_baseurl = 'docs'
+html_theme = 'furo'
+#html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+    "light_logo": "logo-light-mode.png",
+    "dark_logo": "logo-dark-mode.png",
+    # For pydata_sphinx_theme:
+    #"logo": {
+	#    "image_light": "_static/logo-light-mode.png",
+    #    "image_dark": "_static/logo-dark-mode.png",
+    #},
+    #"switcher": {
+    #    "json_url": "https://nvidia.github.io/cuda-python/cuda-bindings/versions.json",
+    #    "version_match": release,
+    #},
+    ## Add light/dark mode and documentation version switcher
+    #"navbar_end": [
+    #    "search-button",
+    #    "theme-switcher",
+    #    "version-switcher",
+    #    "navbar-icon-links",
+    #],
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+suppress_warnings = [
+    # for warnings about multiple possible targets, see NVIDIA/cuda-python#152
+    'ref.python',
+]

cuda_bindings/docs/source/index.rst

@@ -0,0 +1,20 @@
+``cuda.bindings``: Low-level Python Bindings for CUDA
+=====================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   install.md
+   overview.md
+   motivation.md
+   release.md
+   api.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs_src/source/module/driver.rst → cuda_bindings/docs/source/module/driver.rst

@@ -5487,7 +5487,6 @@ Data types used by CUDA driver
 .. autoclass:: cuda.bindings.driver.CUDA_HOST_NODE_PARAMS_v1
 .. autoclass:: cuda.bindings.driver.CUDA_HOST_NODE_PARAMS
 .. autoclass:: cuda.bindings.driver.CUDA_HOST_NODE_PARAMS_v2
-.. autoclass:: cuda.bindings.driver.CUDA_CONDITIONAL_NODE_PARAMS
 .. autoclass:: cuda.bindings.driver.CUgraphEdgeData
 .. autoclass:: cuda.bindings.driver.CUDA_GRAPH_INSTANTIATE_PARAMS
 .. autoclass:: cuda.bindings.driver.CUlaunchMemSyncDomainMap
@@ -5586,10 +5585,6 @@ Data types used by CUDA driver
 
     CUDA API version number
 
-.. autoattribute:: cuda.bindings.driver.CU_UUID_HAS_BEEN_DEFINED
-
-    CUDA UUID types
-
 .. autoattribute:: cuda.bindings.driver.CU_IPC_HANDLE_SIZE
 
     CUDA IPC handle size
@@ -5619,7 +5614,6 @@ Data types used by CUDA driver
     See details of the \link_sync_behavior
 
 .. autoattribute:: cuda.bindings.driver.CU_COMPUTE_ACCELERATED_TARGET_BASE
-.. autoattribute:: cuda.bindings.driver.CUDA_CB
 .. autoattribute:: cuda.bindings.driver.CU_GRAPH_COND_ASSIGN_DEFAULT
 
     Conditional node handle flags Default value is applied when graph is launched.
@@ -6708,8 +6702,6 @@ Even if the green contexts have disjoint SM partitions, it is not guaranteed tha
         Streaming multiprocessors related information
 
 .. autoclass:: cuda.bindings.driver.CUdevResourceDesc
-.. autoclass:: cuda.bindings.driver.CUdevSmResource
-.. autofunction:: cuda.bindings.driver._CONCAT_OUTER
 .. autofunction:: cuda.bindings.driver.cuGreenCtxCreate
 .. autofunction:: cuda.bindings.driver.cuGreenCtxDestroy
 .. autofunction:: cuda.bindings.driver.cuCtxFromGreenCtx
@@ -6724,8 +6716,6 @@ Even if the green contexts have disjoint SM partitions, it is not guaranteed tha
 .. autofunction:: cuda.bindings.driver.cuGreenCtxStreamCreate
 .. autoattribute:: cuda.bindings.driver.RESOURCE_ABI_VERSION
 .. autoattribute:: cuda.bindings.driver.RESOURCE_ABI_EXTERNAL_BYTES
-.. autoattribute:: cuda.bindings.driver._CONCAT_INNER
-.. autoattribute:: cuda.bindings.driver._CONCAT_OUTER
 
 EGL Interoperability
 --------------------

docs_src/source/module/runtime.rst → cuda_bindings/docs/source/module/runtime.rst

@@ -4964,7 +4964,6 @@ Data types used by CUDA Runtime
 .. autoclass:: cuda.bindings.runtime.cudaGraphExecUpdateResultInfo
 .. autoclass:: cuda.bindings.runtime.cudaGraphDeviceNode_t
 .. autoclass:: cuda.bindings.runtime.cudaLaunchMemSyncDomainMap
-.. autoclass:: cuda.bindings.runtime.cudaLaunchAttributeValue
 .. autoclass:: cuda.bindings.runtime.cudaLaunchAttribute
 .. autoclass:: cuda.bindings.runtime.cudaAsyncCallbackHandle_t
 .. autoclass:: cuda.bindings.runtime.cudaAsyncNotificationInfo_t
@@ -5199,11 +5198,6 @@ Data types used by CUDA Runtime
 
     Indicates that the layered sparse CUDA array or CUDA mipmapped array has a single mip tail region for all layers
 
-.. autoattribute:: cuda.bindings.runtime.CUDART_CB
-.. autoattribute:: cuda.bindings.runtime.CU_UUID_HAS_BEEN_DEFINED
-
-    CUDA UUID types
-
 .. autoattribute:: cuda.bindings.runtime.CUDA_IPC_HANDLE_SIZE
 
     CUDA IPC Handle Size

cuda_bindings/docs/versions.json

@@ -0,0 +1,4 @@
+{
+    "latest"  : "latest",
+    "12.6.1"  : "12.6.1"
+}

docs_src/Makefile → cuda_core/docs/Makefile

@@ -3,18 +3,18 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -j auto
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = build/html/${SPHINX_CUDA_CORE_VER}
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -b help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

cuda_core/docs/README.md

@@ -0,0 +1,11 @@
+# Build the documentation
+
+1. Install the `cuda-core` package of the version that we need to document.
+2. Ensure the version is included in the [`versions.json`](./versions.json).
+3. Build the docs with `./build_docs.sh`.
+4. The html artifacts should be available under both `./build/html/latest` and `./build/html/<version>`.
+
+Alternatively, we can build all the docs at once by running [`cuda_python/docs/build_all_docs.sh`](../../cuda_python/docs/build_all_docs.sh).
+
+To publish the docs with the built version, it is important to note that the html files of older versions
+should be kept intact, in order for the version selection (through `versions.json`) to work.