diff --git a/cuda_bindings/docs/Makefile b/cuda_bindings/docs/Makefile new file mode 100644 index 00000000..75f2ef6c --- /dev/null +++ b/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) diff --git a/cuda_bindings/docs/README.md b/cuda_bindings/docs/README.md new file mode 100644 index 00000000..a5e65842 --- /dev/null +++ b/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/`. + +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. diff --git a/cuda_bindings/docs/build_docs.sh b/cuda_bindings/docs/build_docs.sh new file mode 100755 index 00000000..4c8dd837 --- /dev/null +++ b/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 diff --git a/docs_src/make.bat b/cuda_bindings/docs/make.bat similarity index 100% rename from docs_src/make.bat rename to cuda_bindings/docs/make.bat diff --git a/docs_src/source/_static/images/Nsigth-Compute-CLI-625x473.png b/cuda_bindings/docs/source/_static/images/Nsigth-Compute-CLI-625x473.png similarity index 100% rename from docs_src/source/_static/images/Nsigth-Compute-CLI-625x473.png rename to cuda_bindings/docs/source/_static/images/Nsigth-Compute-CLI-625x473.png diff --git a/cuda_bindings/docs/source/_static/javascripts/version_dropdown.js b/cuda_bindings/docs/source/_static/javascripts/version_dropdown.js new file mode 100644 index 00000000..29860a8f --- /dev/null +++ b/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); + }); +} diff --git a/docs_src/source/_static/logo-dark-mode.png b/cuda_bindings/docs/source/_static/logo-dark-mode.png similarity index 100% rename from docs_src/source/_static/logo-dark-mode.png rename to cuda_bindings/docs/source/_static/logo-dark-mode.png diff --git a/docs_src/source/_static/logo-light-mode.png b/cuda_bindings/docs/source/_static/logo-light-mode.png similarity index 100% rename from docs_src/source/_static/logo-light-mode.png rename to cuda_bindings/docs/source/_static/logo-light-mode.png diff --git a/cuda_bindings/docs/source/_templates/main.html b/cuda_bindings/docs/source/_templates/main.html new file mode 100644 index 00000000..b5e870a2 --- /dev/null +++ b/cuda_bindings/docs/source/_templates/main.html @@ -0,0 +1,13 @@ + + + + + + + + +

If this page does not refresh automatically, then please direct your browser to + our latest docs. +

+ + diff --git a/cuda_bindings/docs/source/_templates/sidebar/variant-selector.html b/cuda_bindings/docs/source/_templates/sidebar/variant-selector.html new file mode 100644 index 00000000..b041194c --- /dev/null +++ b/cuda_bindings/docs/source/_templates/sidebar/variant-selector.html @@ -0,0 +1,24 @@ +
+ + cuda-bindings + v: {{ version }} + + +
+
+
+
+ + + diff --git a/docs_src/source/api.rst b/cuda_bindings/docs/source/api.rst similarity index 100% rename from docs_src/source/api.rst rename to cuda_bindings/docs/source/api.rst diff --git a/cuda_bindings/docs/source/conf.py b/cuda_bindings/docs/source/conf.py new file mode 100644 index 00000000..be6f5517 --- /dev/null +++ b/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', +] diff --git a/cuda_bindings/docs/source/index.rst b/cuda_bindings/docs/source/index.rst new file mode 100644 index 00000000..b5bcdd0d --- /dev/null +++ b/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` diff --git a/docs_src/source/install.md b/cuda_bindings/docs/source/install.md similarity index 100% rename from docs_src/source/install.md rename to cuda_bindings/docs/source/install.md diff --git a/docs_src/source/module/driver.rst b/cuda_bindings/docs/source/module/driver.rst similarity index 99% rename from docs_src/source/module/driver.rst rename to cuda_bindings/docs/source/module/driver.rst index 694c81c7..c70f742d 100644 --- a/docs_src/source/module/driver.rst +++ b/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 -------------------- diff --git a/docs_src/source/module/nvrtc.rst b/cuda_bindings/docs/source/module/nvrtc.rst similarity index 100% rename from docs_src/source/module/nvrtc.rst rename to cuda_bindings/docs/source/module/nvrtc.rst diff --git a/docs_src/source/module/runtime.rst b/cuda_bindings/docs/source/module/runtime.rst similarity index 99% rename from docs_src/source/module/runtime.rst rename to cuda_bindings/docs/source/module/runtime.rst index 55687b68..3eaeb695 100644 --- a/docs_src/source/module/runtime.rst +++ b/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 diff --git a/docs_src/source/motivation.md b/cuda_bindings/docs/source/motivation.md similarity index 100% rename from docs_src/source/motivation.md rename to cuda_bindings/docs/source/motivation.md diff --git a/docs_src/source/overview.md b/cuda_bindings/docs/source/overview.md similarity index 100% rename from docs_src/source/overview.md rename to cuda_bindings/docs/source/overview.md diff --git a/docs_src/source/release.md b/cuda_bindings/docs/source/release.md similarity index 100% rename from docs_src/source/release.md rename to cuda_bindings/docs/source/release.md diff --git a/docs_src/source/release/11.4.0-notes.md b/cuda_bindings/docs/source/release/11.4.0-notes.md similarity index 100% rename from docs_src/source/release/11.4.0-notes.md rename to cuda_bindings/docs/source/release/11.4.0-notes.md diff --git a/docs_src/source/release/11.5.0-notes.md b/cuda_bindings/docs/source/release/11.5.0-notes.md similarity index 100% rename from docs_src/source/release/11.5.0-notes.md rename to cuda_bindings/docs/source/release/11.5.0-notes.md diff --git a/docs_src/source/release/11.6.0-notes.md b/cuda_bindings/docs/source/release/11.6.0-notes.md similarity index 100% rename from docs_src/source/release/11.6.0-notes.md rename to cuda_bindings/docs/source/release/11.6.0-notes.md diff --git a/docs_src/source/release/11.6.1-notes.md b/cuda_bindings/docs/source/release/11.6.1-notes.md similarity index 100% rename from docs_src/source/release/11.6.1-notes.md rename to cuda_bindings/docs/source/release/11.6.1-notes.md diff --git a/docs_src/source/release/11.7.0-notes.md b/cuda_bindings/docs/source/release/11.7.0-notes.md similarity index 100% rename from docs_src/source/release/11.7.0-notes.md rename to cuda_bindings/docs/source/release/11.7.0-notes.md diff --git a/docs_src/source/release/11.7.1-notes.md b/cuda_bindings/docs/source/release/11.7.1-notes.md similarity index 100% rename from docs_src/source/release/11.7.1-notes.md rename to cuda_bindings/docs/source/release/11.7.1-notes.md diff --git a/docs_src/source/release/11.8.0-notes.md b/cuda_bindings/docs/source/release/11.8.0-notes.md similarity index 100% rename from docs_src/source/release/11.8.0-notes.md rename to cuda_bindings/docs/source/release/11.8.0-notes.md diff --git a/docs_src/source/release/11.8.1-notes.md b/cuda_bindings/docs/source/release/11.8.1-notes.md similarity index 100% rename from docs_src/source/release/11.8.1-notes.md rename to cuda_bindings/docs/source/release/11.8.1-notes.md diff --git a/docs_src/source/release/11.8.2-notes.md b/cuda_bindings/docs/source/release/11.8.2-notes.md similarity index 100% rename from docs_src/source/release/11.8.2-notes.md rename to cuda_bindings/docs/source/release/11.8.2-notes.md diff --git a/docs_src/source/release/11.8.3-notes.md b/cuda_bindings/docs/source/release/11.8.3-notes.md similarity index 100% rename from docs_src/source/release/11.8.3-notes.md rename to cuda_bindings/docs/source/release/11.8.3-notes.md diff --git a/docs_src/source/release/11.8.4-notes.md b/cuda_bindings/docs/source/release/11.8.4-notes.md similarity index 100% rename from docs_src/source/release/11.8.4-notes.md rename to cuda_bindings/docs/source/release/11.8.4-notes.md diff --git a/docs_src/source/release/12.0.0-notes.md b/cuda_bindings/docs/source/release/12.0.0-notes.md similarity index 100% rename from docs_src/source/release/12.0.0-notes.md rename to cuda_bindings/docs/source/release/12.0.0-notes.md diff --git a/docs_src/source/release/12.1.0-notes.md b/cuda_bindings/docs/source/release/12.1.0-notes.md similarity index 100% rename from docs_src/source/release/12.1.0-notes.md rename to cuda_bindings/docs/source/release/12.1.0-notes.md diff --git a/docs_src/source/release/12.2.0-notes.md b/cuda_bindings/docs/source/release/12.2.0-notes.md similarity index 100% rename from docs_src/source/release/12.2.0-notes.md rename to cuda_bindings/docs/source/release/12.2.0-notes.md diff --git a/docs_src/source/release/12.2.1-notes.md b/cuda_bindings/docs/source/release/12.2.1-notes.md similarity index 100% rename from docs_src/source/release/12.2.1-notes.md rename to cuda_bindings/docs/source/release/12.2.1-notes.md diff --git a/docs_src/source/release/12.3.0-notes.md b/cuda_bindings/docs/source/release/12.3.0-notes.md similarity index 100% rename from docs_src/source/release/12.3.0-notes.md rename to cuda_bindings/docs/source/release/12.3.0-notes.md diff --git a/docs_src/source/release/12.4.0-notes.md b/cuda_bindings/docs/source/release/12.4.0-notes.md similarity index 100% rename from docs_src/source/release/12.4.0-notes.md rename to cuda_bindings/docs/source/release/12.4.0-notes.md diff --git a/docs_src/source/release/12.5.0-notes.md b/cuda_bindings/docs/source/release/12.5.0-notes.md similarity index 100% rename from docs_src/source/release/12.5.0-notes.md rename to cuda_bindings/docs/source/release/12.5.0-notes.md diff --git a/docs_src/source/release/12.6.0-notes.md b/cuda_bindings/docs/source/release/12.6.0-notes.md similarity index 100% rename from docs_src/source/release/12.6.0-notes.md rename to cuda_bindings/docs/source/release/12.6.0-notes.md diff --git a/docs_src/source/release/12.6.1-notes.md b/cuda_bindings/docs/source/release/12.6.1-notes.md similarity index 100% rename from docs_src/source/release/12.6.1-notes.md rename to cuda_bindings/docs/source/release/12.6.1-notes.md diff --git a/cuda_bindings/docs/versions.json b/cuda_bindings/docs/versions.json new file mode 100644 index 00000000..57fe3420 --- /dev/null +++ b/cuda_bindings/docs/versions.json @@ -0,0 +1,4 @@ +{ + "latest" : "latest", + "12.6.1" : "12.6.1" +} diff --git a/docs_src/Makefile b/cuda_core/docs/Makefile similarity index 69% rename from docs_src/Makefile rename to cuda_core/docs/Makefile index d0c3cbf1..3f1222e8 100644 --- a/docs_src/Makefile +++ b/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) diff --git a/cuda_core/docs/README.md b/cuda_core/docs/README.md new file mode 100644 index 00000000..7402ba68 --- /dev/null +++ b/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/`. + +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. diff --git a/cuda_core/docs/build_docs.sh b/cuda_core/docs/build_docs.sh new file mode 100755 index 00000000..d4cd5627 --- /dev/null +++ b/cuda_core/docs/build_docs.sh @@ -0,0 +1,33 @@ +#!/bin/bash + +set -ex + +# SPHINX_CUDA_CORE_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_CORE_VER}" ]]; then + export SPHINX_CUDA_CORE_VER=$(python -c "from importlib.metadata import version; print(version('cuda-core'))" \ + | 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_CORE_VER} build/html/latest + +# ensure that the Sphinx reference uses the latest docs +cp build/html/latest/objects.inv build/html + +# clean up previously auto-generated files +rm -rf source/generated/ diff --git a/cuda_core/docs/source/_static/javascripts/version_dropdown.js b/cuda_core/docs/source/_static/javascripts/version_dropdown.js new file mode 100644 index 00000000..29860a8f --- /dev/null +++ b/cuda_core/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); + }); +} diff --git a/cuda_core/docs/source/_static/logo-dark-mode.png b/cuda_core/docs/source/_static/logo-dark-mode.png new file mode 100644 index 00000000..6b005a28 Binary files /dev/null and b/cuda_core/docs/source/_static/logo-dark-mode.png differ diff --git a/cuda_core/docs/source/_static/logo-light-mode.png b/cuda_core/docs/source/_static/logo-light-mode.png new file mode 100644 index 00000000..c07d6848 Binary files /dev/null and b/cuda_core/docs/source/_static/logo-light-mode.png differ diff --git a/cuda_core/docs/source/_templates/main.html b/cuda_core/docs/source/_templates/main.html new file mode 100644 index 00000000..b5e870a2 --- /dev/null +++ b/cuda_core/docs/source/_templates/main.html @@ -0,0 +1,13 @@ + + + + + + + + +

If this page does not refresh automatically, then please direct your browser to + our latest docs. +

+ + diff --git a/cuda_core/docs/source/_templates/sidebar/variant-selector.html b/cuda_core/docs/source/_templates/sidebar/variant-selector.html new file mode 100644 index 00000000..7110d24a --- /dev/null +++ b/cuda_core/docs/source/_templates/sidebar/variant-selector.html @@ -0,0 +1,24 @@ +
+ + cuda-core + v: {{ version }} + + +
+
+
+
+ + + diff --git a/cuda_core/docs/source/api.rst b/cuda_core/docs/source/api.rst new file mode 100644 index 00000000..1f4b8a69 --- /dev/null +++ b/cuda_core/docs/source/api.rst @@ -0,0 +1,20 @@ +.. module:: cuda.core + +``cuda.core`` API Reference +=========================== + +CUDA runtime +------------ + +.. autosummary:: + :toctree: generated/ + + Device + +CUDA compilation toolchain +-------------------------- + +.. autosummary:: + :toctree: generated/ + + Program diff --git a/docs_src/source/conf.py b/cuda_core/docs/source/conf.py similarity index 73% rename from docs_src/source/conf.py rename to cuda_core/docs/source/conf.py index 62de0de1..4be77656 100644 --- a/docs_src/source/conf.py +++ b/cuda_core/docs/source/conf.py @@ -9,20 +9,19 @@ # 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 os # import sys # sys.path.insert(0, os.path.abspath('.')) # -- Project information ----------------------------------------------------- -project = 'CUDA Python' -copyright = '2021-2024, NVIDIA' +project = 'cuda.core' +copyright = '2024, NVIDIA' author = 'NVIDIA' # The full version, including alpha/beta/rc tags -release = '12.6.1' +release = os.environ["SPHINX_CUDA_CORE_VER"] # -- General configuration --------------------------------------------------- @@ -32,14 +31,12 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', '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'] @@ -52,13 +49,28 @@ # 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 = 'pydata_sphinx_theme' html_theme_options = { - "light_logo": "logo-light-mode.png", + "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-core/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, diff --git a/cuda_core/docs/source/index.rst b/cuda_core/docs/source/index.rst new file mode 100644 index 00000000..15bde572 --- /dev/null +++ b/cuda_core/docs/source/index.rst @@ -0,0 +1,21 @@ +``cuda.core``: Pythonic access to CUDA core functionalities +=========================================================== + +The new Python module ``cuda.core`` offers idiomatic, pythonic access to CUDA runtime +and other functionalities. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + release.md + install.md + api.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/cuda_core/docs/source/install.md b/cuda_core/docs/source/install.md new file mode 100644 index 00000000..593f7225 --- /dev/null +++ b/cuda_core/docs/source/install.md @@ -0,0 +1,29 @@ +# Installation + +## Runtime Requirements + +`cuda.core` is supported on all platforms that CUDA is supported. Specific +dependencies are as follows: + +* Driver: Linux (450.80.02 or later) Windows (456.38 or later) +* CUDA Toolkit 12.0 to 12.6 + + +## Installing from PyPI + +Coming soon! + + +## Installing from Conda + +Coming soon! + + +## Installing from Source + +```shell +$ git clone https://github.com/NVIDIA/cuda-python +$ cd cuda-python/cuda_core +$ pip install . +``` +For now `cuda-python` (`cuda-bindings` later) is a required dependency. diff --git a/cuda_core/docs/source/release.md b/cuda_core/docs/source/release.md new file mode 100644 index 00000000..9705cb64 --- /dev/null +++ b/cuda_core/docs/source/release.md @@ -0,0 +1,9 @@ +# Release Notes + +```{toctree} +--- +maxdepth: 3 +--- + + 0.0.1 +``` diff --git a/cuda_core/docs/source/release/0.0.1-notes.md b/cuda_core/docs/source/release/0.0.1-notes.md new file mode 100644 index 00000000..2247e0cb --- /dev/null +++ b/cuda_core/docs/source/release/0.0.1-notes.md @@ -0,0 +1,15 @@ +# ``cuda.core`` Release notes + +Released on Oct XX, 2024 + +## Hightlights +- Initial beta 1 release +- Supports all platforms that CUDA is supported +- Supports all CUDA 12.x drivers +- Supports all CUDA 12.x Toolkits +- Pythonic CUDA runtime and other core functionalities + +## Limitations + +- Source code release only; Python packages coming in a future release +- Support for CUDA 11.x coming in the next release diff --git a/cuda_core/docs/versions.json b/cuda_core/docs/versions.json new file mode 100644 index 00000000..33087987 --- /dev/null +++ b/cuda_core/docs/versions.json @@ -0,0 +1,4 @@ +{ + "latest" : "latest", + "0.0.1" : "0.0.1" +} diff --git a/cuda_python/docs/Makefile b/cuda_python/docs/Makefile new file mode 100644 index 00000000..a84f5703 --- /dev/null +++ b/cuda_python/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_PYTHON_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) diff --git a/cuda_python/docs/README.md b/cuda_python/docs/README.md new file mode 100644 index 00000000..4cf18ee7 --- /dev/null +++ b/cuda_python/docs/README.md @@ -0,0 +1,23 @@ +# Build the documentation + +1. Ensure the version is included in the [`versions.json`](./versions.json). +2. Build the docs with `./build_docs.sh`. +3. The html artifacts should be available under both `./build/html/latest` and `./build/html/`. + +Alternatively, we can build all the docs at once by running [`./build_all_docs.sh`](./build_all_docs.sh). + +When building the docs, some (but not all) of the urls can be rendered/examined locally by setting the environment +variable `CUDA_PYTHON_DOMAIN` as follows: +```shell +CUDA_PYTHON_DOMAIN="http://localhost:1234/" ./build_all_docs.sh +python -m http.server -d build/html 1234 +``` +If the docs are built on a remote machine, you can set up the ssh tunnel in a separate terminal session +via +```shell +ssh -L 1234:localhost:1234 username@hostname +``` +Then browse the built docs by visiting `http://localhost:1234/` on a local machine. + +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. diff --git a/cuda_python/docs/build_all_docs.sh b/cuda_python/docs/build_all_docs.sh new file mode 100755 index 00000000..030463b7 --- /dev/null +++ b/cuda_python/docs/build_all_docs.sh @@ -0,0 +1,27 @@ +#!/bin/bash + +set -ex + +# build cuda-python docs +rm -rf build +./build_docs.sh + +# build cuda-bindings docs +CUDA_BINDINGS_PATH=build/html/cuda-bindings +mkdir -p $CUDA_BINDINGS_PATH +pushd . +cd ../../cuda_bindings/docs +rm -rf build +./build_docs.sh +cp -r build/html/* "$(dirs -l +1)"/$CUDA_BINDINGS_PATH +popd + +# build cuda-core docs +CUDA_CORE_PATH=build/html/cuda-core +mkdir -p $CUDA_CORE_PATH +pushd . +cd ../../cuda_core/docs +rm -rf build +./build_docs.sh +cp -r build/html/* "$(dirs -l +1)"/$CUDA_CORE_PATH +popd diff --git a/cuda_python/docs/build_docs.sh b/cuda_python/docs/build_docs.sh new file mode 100755 index 00000000..f1dbcbe1 --- /dev/null +++ b/cuda_python/docs/build_docs.sh @@ -0,0 +1,33 @@ +#!/bin/bash + +set -ex + +# SPHINX_CUDA_PYTHON_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_PYTHON_VER}" ]]; then + export SPHINX_CUDA_PYTHON_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_PYTHON_VER} build/html/latest + +# ensure that the Sphinx reference uses the latest docs +cp build/html/latest/objects.inv build/html + +# clean up previously auto-generated files +rm -rf source/generated/ diff --git a/docs_src/environment-docs.yml b/cuda_python/docs/environment-docs.yml similarity index 100% rename from docs_src/environment-docs.yml rename to cuda_python/docs/environment-docs.yml diff --git a/cuda_python/docs/source/_static/javascripts/version_dropdown.js b/cuda_python/docs/source/_static/javascripts/version_dropdown.js new file mode 100644 index 00000000..29860a8f --- /dev/null +++ b/cuda_python/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); + }); +} diff --git a/cuda_python/docs/source/_static/logo-dark-mode.png b/cuda_python/docs/source/_static/logo-dark-mode.png new file mode 100644 index 00000000..6b005a28 Binary files /dev/null and b/cuda_python/docs/source/_static/logo-dark-mode.png differ diff --git a/cuda_python/docs/source/_static/logo-light-mode.png b/cuda_python/docs/source/_static/logo-light-mode.png new file mode 100644 index 00000000..c07d6848 Binary files /dev/null and b/cuda_python/docs/source/_static/logo-light-mode.png differ diff --git a/cuda_python/docs/source/_templates/main.html b/cuda_python/docs/source/_templates/main.html new file mode 100644 index 00000000..b5e870a2 --- /dev/null +++ b/cuda_python/docs/source/_templates/main.html @@ -0,0 +1,13 @@ + + + + + + + + +

If this page does not refresh automatically, then please direct your browser to + our latest docs. +

+ + diff --git a/cuda_python/docs/source/_templates/sidebar/variant-selector.html b/cuda_python/docs/source/_templates/sidebar/variant-selector.html new file mode 100644 index 00000000..bec47cf4 --- /dev/null +++ b/cuda_python/docs/source/_templates/sidebar/variant-selector.html @@ -0,0 +1,24 @@ +
+ + cuda-python + v: {{ version }} + + +
+
+
+
+ + + diff --git a/docs_src/source/conduct.md b/cuda_python/docs/source/conduct.md similarity index 100% rename from docs_src/source/conduct.md rename to cuda_python/docs/source/conduct.md diff --git a/cuda_python/docs/source/conf.py b/cuda_python/docs/source/conf.py new file mode 100644 index 00000000..8a5ab87f --- /dev/null +++ b/cuda_python/docs/source/conf.py @@ -0,0 +1,90 @@ +# 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 Python' +copyright = '2021-2024, NVIDIA' +author = 'NVIDIA' + +# The full version, including alpha/beta/rc tags +release = os.environ["SPHINX_CUDA_PYTHON_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' +] + +# 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-core/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'] + +# Allow overwriting CUDA Python's domain name for local development. See: +# - https://stackoverflow.com/a/61694897/2344149 +# - https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog +CUDA_PYTHON_DOMAIN = os.environ.get('CUDA_PYTHON_DOMAIN', + 'https://nvidia.github.io/cuda-python') +rst_epilog = f""" +.. _cuda.core: {CUDA_PYTHON_DOMAIN}/cuda-core/latest +.. _cuda.bindings: {CUDA_PYTHON_DOMAIN}/cuda-bindings/latest +.. _cuda.cooperative: https://nvidia.github.io/cccl/cuda_cooperative/ +.. _cuda.parallel: https://nvidia.github.io/cccl/cuda_parallel/ +""" diff --git a/docs_src/source/contribute.md b/cuda_python/docs/source/contribute.md similarity index 100% rename from docs_src/source/contribute.md rename to cuda_python/docs/source/contribute.md diff --git a/cuda_python/docs/source/index.rst b/cuda_python/docs/source/index.rst new file mode 100644 index 00000000..4b17a1e9 --- /dev/null +++ b/cuda_python/docs/source/index.rst @@ -0,0 +1,34 @@ +CUDA Python +=========== + +CUDA Python is the home for accessing NVIDIA's CUDA platform from Python. It consists of +multiple components: + +- `cuda.core`_: Pythonic access to CUDA runtime and other core functionalities +- `cuda.bindings`_: Low-level Python bindings to CUDA C APIs +- `cuda.cooperative`_: Pythonic exposure of CUB cooperative algorithms +- `cuda.parallel`_: Pythonic exposure of Thrust parallel algorithms + +For access to NVIDIA Math Libraries, please refer to `nvmath-python`_. + +.. _nvmath-python: https://docs.nvidia.com/cuda/nvmath-python/latest + +CUDA Python is currently undergoing an overhaul to improve existing and bring up new components. +All of the previously available functionalities from the ``cuda-python`` package will continue to +be available, please refer to the `cuda.bindings`_ documentation for installation guide and further detail. + +.. + The urls above can be auto-inserted by Sphinx (see rst_epilog in conf.py), but + not for the urls below, which must be hard-coded due to Sphinx limitation... + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + release.md + cuda.core + cuda.bindings + cuda.cooperative + cuda.parallel + conduct.md + contribute.md diff --git a/cuda_python/docs/source/release.md b/cuda_python/docs/source/release.md new file mode 100644 index 00000000..7af89792 --- /dev/null +++ b/cuda_python/docs/source/release.md @@ -0,0 +1,9 @@ +# Release Notes + +```{toctree} +--- +maxdepth: 3 +--- + + 12.6.1 +``` diff --git a/cuda_python/docs/source/release/12.6.1-notes.md b/cuda_python/docs/source/release/12.6.1-notes.md new file mode 100644 index 00000000..9a812afc --- /dev/null +++ b/cuda_python/docs/source/release/12.6.1-notes.md @@ -0,0 +1,12 @@ +# CUDA Python Release notes + +Released on Oct 7, 2024 + +## Included components + +- [`cuda.bindings` 12.6.1](https://nvidia.github.io/cuda-python/cuda-bindings/12.6.1/release/12.6.1-notes.html) + + +## Hightlights +- Internal layout refactoring to prepare for the `cuda-python` metapackage ([Issue #90](https://github.com/NVIDIA/cuda-python/issues/90), + [Issue #75](https://github.com/NVIDIA/cuda-python/issues/75)) diff --git a/cuda_python/docs/versions.json b/cuda_python/docs/versions.json new file mode 100644 index 00000000..57fe3420 --- /dev/null +++ b/cuda_python/docs/versions.json @@ -0,0 +1,4 @@ +{ + "latest" : "latest", + "12.6.1" : "12.6.1" +} diff --git a/docs_src/source/index.rst b/docs_src/source/index.rst deleted file mode 100644 index 278fa165..00000000 --- a/docs_src/source/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. CUDA Python documentation master file, created by - sphinx-quickstart on Wed Jul 7 12:14:05 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -CUDA Python Manual -======================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - install.md - overview.md - motivation.md - conduct.md - contribute.md - release.md - api.rst - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`