Fix docs (#656)

* Fix Python doc generation
* Remove `ChannelTrigger` and fix `ProxyTrigger`
* Fixed package versions for consistency

Author: chhwang

.github/workflows/doc-build.yaml

@@ -10,25 +10,26 @@ permissions:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y doxygen graphviz
+          sudo apt-get install -y doxygen=1.9.1-* graphviz
           pip install -r docs/requirements.txt
 
       - name: Build docs
         run: |
           cd docs
+          rm -rf doxygen _build py_api
           doxygen
           make html
           touch _build/html/.nojekyll

.github/workflows/gh-pages.yml

@@ -22,22 +22,23 @@ concurrency:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Setup python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.12'
       - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y doxygen graphviz
+          sudo apt-get install -y doxygen=1.9.1-* graphviz
           pip install -r docs/requirements.txt
       - name: Build docs
         run: |
           cd docs
+          rm -rf doxygen _build py_api
           doxygen
           make html
           touch _build/html/.nojekyll

.github/workflows/update-version.yml

@@ -263,12 +263,6 @@ TAB_SIZE               = 2
 
 ALIASES                =
 
-# This tag can be used to specify a number of word-keyword mappings (TCL only).
-# A mapping has the form "name=value". For example adding "class=itcl::class"
-# will allow you to use the command class in the itcl::class meaning.
-
-TCL_SUBST              =
-
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
 # instance, some of the names that are used will be different. The list of all
@@ -829,10 +823,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include/mscclpp \
-                         ../README.md \
-                         quickstart.md \
-                         performance-ndmv4.md
+INPUT                  = ../include/mscclpp
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1030,7 +1021,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ../README.md
+USE_MDFILE_AS_MAINPAGE =
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1158,13 +1149,6 @@ CLANG_DATABASE_PATH    =
 
 ALPHABETICAL_INDEX     = YES
 
-# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
-# which the alphabetical index list will be split.
-# Minimum value: 1, maximum value: 20, default value: 5.
-# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
-
-COLS_IN_ALPHA_INDEX    = 5
-
 # In case all classes in a project start with a common prefix, all classes will
 # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
 # can be used to specify a prefix (or a list of prefixes) that should be ignored

docs/Doxyfile

@@ -17,4 +17,5 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	@cd .. && python3 -m setuptools_scm --force-write-version-files
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -3,21 +3,34 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+
+# -- Path setup --------------------------------------------------------------
+import sys
+import importlib.util
+from pathlib import Path
+
+# Add the python package to sys.path so Sphinx can find it
+project_root = Path(__file__).parent.parent
+python_path = project_root / "python"
+sys.path.insert(0, str(python_path))
+
+# -- Project version -----------------------------------------------------
+spec = importlib.util.spec_from_file_location("_version", python_path / "mscclpp" / "_version.py")
+version_module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(version_module)
+version = version_module.__version__
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "mscclpp"
 copyright = "2025, MSCCL++ Team"
 author = "MSCCL++ Team"
-release = "v0.8.0"
+release = "v" + version
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-import os, sys
-
-sys.path.insert(0, os.path.abspath("../python"))
-
 extensions = [
     "breathe",
     "myst_parser",
@@ -36,7 +49,7 @@
     "show-inheritance": True,
 }
 # only mock the C-extension when using the source tree
-autodoc_mock_imports = ["mscclpp._mscclpp", "sortedcontainers"]
+autodoc_mock_imports = ["mscclpp._version", "mscclpp._mscclpp", "cupy", "mpi4py", "numpy", "sortedcontainers"]
 autodoc_typehints = "description"
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True

docs/conf.py

@@ -231,8 +231,6 @@ Channel Device Interfaces
 .. doxygenstruct:: mscclpp::BasePortChannelDeviceHandle
    :members:
 
-.. doxygenunion:: mscclpp::ChannelTrigger
-
 .. doxygenunion:: mscclpp::LL16Packet
 
 .. doxygenunion:: mscclpp::LL8Packet
@@ -267,8 +265,7 @@ FIFO Device Interfaces
 .. doxygenstruct:: mscclpp::FifoDeviceHandle
    :members:
 
-.. doxygenstruct:: mscclpp::ProxyTrigger
-   :members:
+.. doxygenunion:: mscclpp::ProxyTrigger
 
 .. doxygenvariable:: mscclpp::TriggerBitsFifoReserved
 

docs/cpp_api.rst

@@ -13,6 +13,7 @@ You can find the followings from this documentation.
 - **Tutorials:** A step-by-step guide for GPU communication using MSCCL++. :doc:`🔗 <tutorials>`
 - **Programming Guide:** Advanced topics and best practices for using MSCCL++. :doc:`🔗 <programming_guide>`
 - **C++ API Reference:** Detailed documentation of the MSCCL++ C++ API. :doc:`🔗 <cpp_api>`
+- **Python API Reference:** Detailed documentation of the MSCCL++ Python API. :doc:`🔗 <py_api>`
 
 .. toctree::
    :maxdepth: 1

docs/index.rst

@@ -7,4 +7,6 @@ This reference organizes the MSCCL++ Python API.
    :toctree: py_api
    :recursive:
 
-   mscclpp
+   mscclpp.comm
+   mscclpp.utils
+   mscclpp.language

docs/py_api.rst

@@ -162,6 +162,7 @@ $ python3 -m pip install -r ./python/requirements_cuda12.txt
 $ mpirun -tag-output -np 8 python3 ./python/mscclpp_benchmark/allreduce_bench.py
 ```
 
+(nccl-benchmark)=
 ### NCCL/RCCL Benchmark over MSCCL++
 
 We implement [NCCL](https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/api.html) APIs using MSCCL++. How to use: