diff --git a/.github/workflows/doc-build.yaml b/.github/workflows/doc-build.yaml index 78af009e8..6e7524668 100644 --- a/.github/workflows/doc-build.yaml +++ b/.github/workflows/doc-build.yaml @@ -10,7 +10,7 @@ permissions: jobs: build: - runs-on: ubuntu-latest + runs-on: ubuntu-22.04 steps: - name: Checkout uses: actions/checkout@v4 @@ -18,17 +18,18 @@ jobs: - 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 diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 1c2645edf..d5656c783 100644 --- a/.github/workflows/gh-pages.yml +++ b/.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 diff --git a/.github/workflows/update-version.yml b/.github/workflows/update-version.yml deleted file mode 100644 index 977095dfe..000000000 --- a/.github/workflows/update-version.yml +++ /dev/null @@ -1,44 +0,0 @@ -name: Update Version -on: - pull_request: - branches: - - main - - release/** - paths: - - 'VERSION' - -permissions: - contents: write - -jobs: - update-version: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - ref: ${{ github.head_ref }} - fetch-depth: 0 - - - name: Read version - id: read_version - run: echo "VERSION=$(cat VERSION)" >> $GITHUB_ENV - - - name: Update Version in Files - run: | - VERSION=${{ env.VERSION }} - sed -i "s/^release = \".*\"/release = \"v${VERSION}\"/" docs/conf.py - - - name: Commit and Push Changes - run: | - git config user.name "github-actions" - git config user.email "github-actions@github.com" - git add CITATION.cff docs/conf.py || true - if git diff --cached --exit-code; then - echo "No changes to commit." - else - git commit -m "Update version to ${{ env.VERSION }}" - git push - fi - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/Doxyfile b/docs/Doxyfile index 4445399f4..d17aa6eb1 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -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 diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb9..c1fc73650 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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) diff --git a/docs/conf.py b/docs/conf.py index f06783564..38b199d04 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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 diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst index fbfd503d1..6b5f24c0f 100644 --- a/docs/cpp_api.rst +++ b/docs/cpp_api.rst @@ -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 diff --git a/docs/index.rst b/docs/index.rst index d612388fa..ac9d7ec27 100644 --- a/docs/index.rst +++ b/docs/index.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:`🔗 ` - **Programming Guide:** Advanced topics and best practices for using MSCCL++. :doc:`🔗 ` - **C++ API Reference:** Detailed documentation of the MSCCL++ C++ API. :doc:`🔗 ` +- **Python API Reference:** Detailed documentation of the MSCCL++ Python API. :doc:`🔗 ` .. toctree:: :maxdepth: 1 diff --git a/docs/py_api.rst b/docs/py_api.rst index 7acc9273e..5ea39bc33 100644 --- a/docs/py_api.rst +++ b/docs/py_api.rst @@ -7,4 +7,6 @@ This reference organizes the MSCCL++ Python API. :toctree: py_api :recursive: - mscclpp + mscclpp.comm + mscclpp.utils + mscclpp.language diff --git a/docs/quickstart.md b/docs/quickstart.md index 0727963c0..82f79c722 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -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: diff --git a/docs/requirements.txt b/docs/requirements.txt index 99e84802c..42587c9d0 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,7 @@ -breathe +sphinx==8.2.3 +breathe==4.36.0 +myst_parser==4.0.1 sphinx_rtd_theme -myst_parser sphinxcontrib-mermaid sphinx-autodoc-typehints +setuptools_scm diff --git a/docs/tutorials/00-before-you-start.md b/docs/tutorials/00-before-you-start.md index c48fa88e3..d2312c8f6 100644 --- a/docs/tutorials/00-before-you-start.md +++ b/docs/tutorials/00-before-you-start.md @@ -1,6 +1,6 @@ # Before You Start -This tutorial introduces how to use the MSCCL++ Primitive API to write highly flexible and optimized GPU communication kernels from the lowest level. If you are looking for the high-level APIs, please refer to the DSL API or the NCCL API. +This tutorial introduces how to use the MSCCL++ Primitive API to write highly flexible and optimized GPU communication kernels from the lowest level. If you are looking for the high-level APIs, please refer to the [DSL API](../guide/mscclpp-dsl.md) or the [NCCL API](../quickstart.md#nccl-benchmark). ## Hardware Requirements