diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b4eeefa70b..4762cccee6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -17,8 +17,8 @@ jobs: uses: actions/checkout@v3 - name: 'Install dependencies' run: | - pip install sphinx==5.1.1 sphinx_rtd_theme==1.0.0 nbsphinx==0.8.10 IPython ipython_genutils==0.2.0 ipywidgets==8.0.2 astroid==2.15.7 - pip install breathe==4.34.0 sphinx-autoapi==2.0.1 + pip install sphinx==8.1.3 sphinx_rtd_theme==3.0.1 nbsphinx==0.9.5 IPython ipython_genutils==0.2.0 ipywidgets==8.0.2 astroid==3.3.2 + pip install breathe==4.35.0 sphinx-autoapi==3.3.2 sudo apt-get install -y pandoc graphviz doxygen export GIT_SHA=$(git show-ref --hash HEAD) - name: 'Build docs' diff --git a/.gitignore b/.gitignore index 6890911c14..8880784742 100644 --- a/.gitignore +++ b/.gitignore @@ -22,9 +22,7 @@ __pycache__ .hypothesis .devcontainer.json tests/cpp/build/ -docs/_build .ipynb_checkpoints -docs/doxygen *.log CMakeFiles/CMakeSystem.cmake sdist/ diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..409af2d74e --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +_build +doxygen +sphinx_rtd_theme \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb9e..800eeea78a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -16,5 +16,10 @@ 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 - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +%: Makefile sphinx_rtd_theme + PYTHONPATH=sphinx_rtd_theme:$(PYTHONPATH) $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# Patch Sphinx RTD theme 3.0.1 to add version selector in sidebar +sphinx_rtd_theme: + git clone --depth=1 -b 3.0.1 --single-branch https://github.com/readthedocs/sphinx_rtd_theme.git + bash -c "cd sphinx_rtd_theme; git apply ../version_select.patch" diff --git a/docs/conf.py b/docs/conf.py index 7a50ce76cf..7d2d4ea7b9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,38 +2,30 @@ # # See LICENSE for license information. +import datetime import os -import sys -import sphinx_rtd_theme -from sphinx.ext.autodoc.mock import mock -from sphinx.ext.autodoc import between, ClassDocumenter, AttributeDocumenter -from sphinx.util import inspect -from builtins import str -from enum import Enum -import re +import pathlib import subprocess -from pathlib import Path -from datetime import date - -te_path = os.path.dirname(os.path.realpath(__file__)) +from builtins import str -with open(te_path + "/../build_tools/VERSION.txt", "r") as f: - te_version = f.readline().strip() +# Basic project info +project = "Transformer Engine" +author = "NVIDIA CORPORATION & AFFILIATES" +# Copyright statement release_year = 2022 - -current_year = date.today().year +current_year = datetime.date.today().year if current_year == release_year: copyright_year = release_year else: copyright_year = str(release_year) + "-" + str(current_year) +copyright = f"{copyright_year}, NVIDIA CORPORATION & AFFILIATES. All rights reserved." -project = "Transformer Engine" -copyright = "{}, NVIDIA CORPORATION & AFFILIATES. All rights reserved.".format(copyright_year) -author = "NVIDIA CORPORATION & AFFILIATES" +# Transformer Engine root directory +root_path = pathlib.Path(__file__).resolve().parent.parent +# Git hash git_sha = os.getenv("GIT_SHA") - if not git_sha: try: git_sha = ( @@ -44,31 +36,16 @@ ) except: git_sha = "0000000" - git_sha = git_sha[:7] if len(git_sha) > 7 else git_sha -if "dev" in te_version: - version = str(te_version + "-" + git_sha) +# Version +with open(root_path / "build_tools" / "VERSION.txt", "r") as f: + _raw_version = f.readline().strip() +if "dev" in _raw_version: + version = str(_raw_version + "-" + git_sha) else: - version = str(te_version) -release = te_version - -# hack: version is used for html creation, so put the version picker -# link here as well: -option_on = " selected" -option_off = "" -release_opt = option_on -option_nr = 0 -version = ( - version - + """
-Version select: """.format( - option_nr, release_opt - ) -) + version = str(_raw_version) +release = _raw_version # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -92,12 +69,10 @@ pygments_style = "sphinx" - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "sphinx_rtd_theme" -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] html_static_path = ["_static"] html_show_sphinx = False @@ -106,7 +81,12 @@ "css/nvidia_footer.css", ] -html_theme_options = {"display_version": True, "collapse_navigation": False, "logo_only": False} +html_theme_options = { + "collapse_navigation": False, + "logo_only": False, + "version_selector": False, + "language_selector": False, +} napoleon_custom_sections = [ ("Parallelism parameters", "params_style"), @@ -116,8 +96,8 @@ ("FP8-related parameters", "params_style"), ] -breathe_projects = {"TransformerEngine": os.path.abspath("doxygen/xml/")} +breathe_projects = {"TransformerEngine": root_path / "docs" / "doxygen" / "xml"} breathe_default_project = "TransformerEngine" autoapi_generate_api_docs = False -autoapi_dirs = ["../transformer_engine"] +autoapi_dirs = [root_path / "transformer_engine"] diff --git a/docs/version_select.patch b/docs/version_select.patch new file mode 100644 index 0000000000..75f29fff81 --- /dev/null +++ b/docs/version_select.patch @@ -0,0 +1,21 @@ +diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html +index e6a38b1..579eaec 100644 +--- a/sphinx_rtd_theme/layout.html ++++ b/sphinx_rtd_theme/layout.html +@@ -124,6 +124,16 @@ + {%- endif %} + + ++ {# Show TE version and version selector #} ++
++ {{ version }} ++
++ Version select: ++
++ + {%- if READTHEDOCS or DEBUG %} + {%- if theme_version_selector or theme_language_selector %} +