Integrate Python docs (#2196)

* pass docs build options to repo.sh

* Integrate Python docs

* update CI

* Apply suggestions from code review

Co-authored-by: Georgii Evtushenko <[email protected]>

---------

Co-authored-by: Georgii Evtushenko <[email protected]>

.github/actions/docs-build/action.yml

@@ -36,6 +36,8 @@ runs:
         cp -rf ./docs/_build/docs/thrust/latest/* _site/thrust
         mkdir _site/cudax
         cp -rf ./docs/_build/docs/cudax/latest/* _site/cudax
+        mkdir _site/cuda_cooperative
+        cp -rf ./docs/_build/docs/cuda_cooperative/latest/* _site/cuda_cooperative
         ./docs/scrape_docs.bash ./_site
 
     # Update docs as workflow artifact:

docs/cpp.rst

@@ -0,0 +1,52 @@
+.. _cccl-cpp-libraries:
+
+CUDA C++ Core Libraries
+=======================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+
+   libcu++ <https://nvidia.github.io/cccl/libcudacxx/>
+   CUB <https://nvidia.github.io/cccl/cub/>
+   Thrust <https://nvidia.github.io/cccl/thrust/>
+   Cuda Experimental <https://nvidia.github.io/cccl/cudax/>
+
+Welcome to the CUDA Core Compute Libraries (CCCL) libraries for C++.
+
+The concept for the  CCCL C++ librarires grew organically out of the Thrust,
+CUB, and libcudacxx projects that were developed independently over the years
+with a similar goal: to provide high-quality, high-performance, and
+easy-to-use C++ abstractions for CUDA developers. Naturally, there was a lot
+of overlap among the three projects, and it became clear the community would
+be better served by unifying them into a single repository.
+
+- `libcu++ <https://nvidia.github.io/cccl/libcudacxx/>`__
+  is the CUDA C++ Standard Library. It provides an implementation of the C++
+  Standard Library that works in both host and device code. Additionally, it
+  provides abstractions for CUDA-specific hardware features like
+  synchronization primitives, cache control, atomics, and more.
+
+- `CUB <https://nvidia.github.io/cccl/cub/>`__
+  is a lower-level, CUDA-specific library designed for speed-of-light parallel
+  algorithms across all GPU architectures. In addition to device-wide
+  algorithms, it provides *cooperative algorithms* like block-wide reduction
+  and warp-wide scan, providing CUDA kernel developers with building blocks to
+  create speed-of-light, custom kernels.
+
+- `Thrust <https://nvidia.github.io/cccl/thrust/>`__
+  is the C++ parallel algorithms library which inspired the introduction of
+  parallel algorithms to the C++ Standard Library. Thrust's high-level
+  interface greatly enhances programmer productivity while enabling performance
+  portability between GPUs and multicore CPUs via configurable backends that
+  allow using multiple parallel programming frameworks (such as CUDA, TBB, and
+  OpenMP).
+
+- `Cuda Experimental <https://nvidia.github.io/cccl/cudax/>`__
+  is a library of exerimental features that are still in the design process.
+
+The main goal of the CCCL C++ libraries is to fill a similar role that the
+Standard C++ Library fills for Standard C++: provide general-purpose,
+speed-of-light tools to CUDA C++ developers, allowing them to focus on
+solving the problems that matter. Unifying these projects is the first step
+towards realizing that goal.

docs/pycuda/index.rst → docs/cuda_cooperative/index.rst

@@ -1,6 +1,6 @@
-.. _pycudax-module:
+.. _cuda_cooperative-module:
 
-CUDA
+CUDA Cooperative
 ==================================================
 
 .. warning::

docs/gen_docs.bash

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 
-## This script just wraps launching a docs build within a container
-## Tag is passed on as the first argument ${1}
+# This script just wraps launching a repo docs build within a container
+#
+# Additional options, e.g --stage sphinx will be passed on to repo.sh
 
 set -e
 
@@ -36,7 +37,7 @@ if [ ! -n "$(find img -name '*.png')" ]; then
     done
 fi
 
-if ! ./repo.sh docs; then
+if ! ./repo.sh docs "$@"; then
     echo "!!! There were errors while generating"
     exit 1
 fi

docs/index.rst

@@ -1,27 +1,16 @@
-CUDA C++ Core Libraries
-=======================
+CUDA Core Compute Libraries
+===========================
 
 .. toctree::
    :hidden:
    :maxdepth: 3
 
-   libcu++ <https://nvidia.github.io/cccl/libcudacxx/>
-   CUB <https://nvidia.github.io/cccl/cub/>
-   Thrust <https://nvidia.github.io/cccl/thrust/>
-   Cuda Experimental <https://nvidia.github.io/cccl/cudax/>
+   cpp
+   python
 
-Welcome to the CUDA C++ Core Libraries (CCCL) where our mission is to make CUDA C++ more delightful.
+Welcome to the CUDA Core Compute Libraries (CCCL) where our mission is to
+make CUDA C++ and Python more delightful.
 
-The concept for the CUDA C++ Core Libraries (CCCL) grew organically out of the Thrust, CUB, and libcudacxx projects that were developed independently over the years with a similar goal: to provide high-quality, high-performance, and easy-to-use C++ abstractions for CUDA developers.
-Naturally, there was a lot of overlap among the three projects, and it became clear the community would be better served by unifying them into a single repository.
+- :ref:`cccl-cpp-libraries`
 
-- `libcu++ <https://nvidia.github.io/cccl/libcudacxx/>`__ is the CUDA C++ Standard Library. It provides an implementation of the C++ Standard Library that works in both host and device code. Additionally, it provides abstractions for CUDA-specific hardware features like synchronization primitives, cache control, atomics, and more.
-
-- `CUB <https://nvidia.github.io/cccl/cub/>`__ is a lower-level, CUDA-specific library designed for speed-of-light parallel algorithms across all GPU architectures. In addition to device-wide algorithms, it provides *cooperative algorithms* like block-wide reduction and warp-wide scan, providing CUDA kernel developers with building blocks to create speed-of-light, custom kernels.
-
-- `Thrust <https://nvidia.github.io/cccl/thrust/>`__ is the C++ parallel algorithms library which inspired the introduction of parallel algorithms to the C++ Standard Library. Thrust's high-level interface greatly enhances programmer productivity while enabling performance portability between GPUs and multicore CPUs via configurable backends that allow using multiple parallel programming frameworks (such as CUDA, TBB, and OpenMP).
-
-- `Cuda Experimental <https://nvidia.github.io/cccl/cudax/>`__ is a library of exerimental features that are still in the design process.
-
-The main goal of CCCL is to fill a similar role that the Standard C++ Library fills for Standard C++: provide general-purpose, speed-of-light tools to CUDA C++ developers, allowing them to focus on solving the problems that matter.
-Unifying these projects is the first step towards realizing that goal.
+- :ref:`cccl-python-libraries`

docs/python.rst

@@ -0,0 +1,15 @@
+.. _cccl-python-libraries:
+
+CUDA Python Core Libraries
+==========================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+
+   cuda.cooperative <https://nvidia.github.io/cccl/cuda_cooperative/>
+
+Welcome to the CUDA Core Compute Libraries (CCCL) libraries for Python.
+
+- `cuda.cooperative <https://nvidia.github.io/cccl/cuda_cooperative/>`__
+  is a still-experimental library exposing cooperative algorithms to Python.

docs/repo.toml

@@ -25,14 +25,14 @@ sphinx_exclude_patterns = [
     "VERSION.md",
 ]
 
-project_build_order = [ "libcudacxx", "cudax", "cub", "thrust", "cccl", "pycuda" ]
+project_build_order = [ "libcudacxx", "cudax", "cub", "thrust", "cccl", "cuda_cooperative" ]
 
 # deps can be used to link to other projects' documentation
 deps = [
     [ "libcudacxx", "_build/docs/libcudacxx/latest" ],
     [ "cub", "_build/docs/cub/latest" ],
     [ "thrust", "_build/docs/thrust/latest" ],
-    [ "pycuda", "_build/docs/pycuda/latest" ],
+    [ "cuda_cooperative", "_build/docs/cuda_cooperative/latest" ],
 ]
 
 [repo_docs.projects.libcudacxx]
@@ -281,9 +281,9 @@ doxygen_conf_extra = """
   STRIP_FROM_PATH        = ../../thrust
 """
 
-[repo_docs.projects.pycuda]
-name = "pycuda"
-docs_root = "pycuda"
+[repo_docs.projects.cuda_cooperative]
+name = "cuda.cooperative"
+docs_root = "cuda_cooperative"
 logo = "../img/logo.png"
 
 repo_url         = "https://github.com/NVIDIA/cccl/python/cuda"