diff --git a/.ci/docker/requirements-ci.txt b/.ci/docker/requirements-ci.txt index 5527b9b4d6d..4c1b1b7fcc1 100644 --- a/.ci/docker/requirements-ci.txt +++ b/.ci/docker/requirements-ci.txt @@ -30,7 +30,6 @@ sphinx-reredirects==0.1.4 matplotlib>=3.9.4 sphinx-copybutton==0.5.2 # PyTorch Theme --e git+https://github.com/pytorch/pytorch_sphinx_theme.git@pytorch_sphinx_theme2#egg=pytorch_sphinx_theme2 - +pytorch_sphinx_theme2==0.2.0 # script unit test requirements yaspin==3.1.0 diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 7852a76101b..cfc2a441bc5 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -46,14 +46,15 @@ jobs: export CHANNEL=nightly fi - # Get the version of ExecuTorch from REF_NAME and save as ET_VERSION_DOCS - # ET_VERSION_DOCS will be pulled during the doc build to add to the version dropdown - # on the website. See docs/source/conf.py for details - + # Set RELEASE environment variable for tagged releases GITHUB_REF=${{ github.ref }} - echo "$GITHUB_REF" - export ET_VERSION_DOCS="${GITHUB_REF}" - echo "$ET_VERSION_DOCS" + if [[ "${GITHUB_REF}" =~ ^refs/tags/v[0-9]+\.[0-9]+ ]]; then + export RELEASE=true + echo "Building release docs (RELEASE=true)" + else + export RELEASE=false + echo "Building main docs (RELEASE=false)" + fi set -eux diff --git a/.mypy.ini b/.mypy.ini index cd14cbac7ea..da3ab27451c 100644 --- a/.mypy.ini +++ b/.mypy.ini @@ -74,6 +74,12 @@ ignore_missing_imports = True [mypy-pytorch_sphinx_theme] ignore_missing_imports = True +[mypy-pytorch_sphinx_theme2] +ignore_missing_imports = True + +[mypy-executorch.version] +ignore_missing_imports = True + [mypy-ruamel] ignore_missing_imports = True diff --git a/docs/Makefile b/docs/Makefile index 627358d0387..c4f5e571ff8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -13,6 +13,12 @@ BUILDDIR = _build html-noplot: $(SPHINXBUILD) -D plot_gallery=0 -b html $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" +html-stable: + # Stable differs from 'make html' in that it shows the release version + # instead of "main (version)" in the docs and version switcher. + # See conf.py for more details. + RELEASE=true $(MAKE) html + help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/conf.py b/docs/source/conf.py index 78268c8d053..f69fc243255 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -76,25 +76,40 @@ html_favicon = "_static/img/executorch-chip-logo.svg" -# Get ET_VERSION_DOCS during the build. -et_version_docs = os.environ.get("ET_VERSION_DOCS", None) -print(f"et_version_docs: {et_version_docs}") - -# The code below will cut version displayed in the dropdown like this: -# By default, set to "main". -# If it's a tag like refs/tags/v1.2.3-rc4 or refs/tags/v1.2.3, then -# cut to 1.2 -# the version varible is used in layout.html: https://github.com/pytorch/executorch/blob/main/docs/source/_templates/layout.html#L29 -version = release = "main" -if et_version_docs: - if et_version_docs.startswith("refs/tags/v"): - version = ".".join( - et_version_docs.split("/")[-1].split("-")[0].lstrip("v").split(".")[:2] - ) - elif et_version_docs.startswith("refs/heads/release/"): - version = et_version_docs.split("/")[-1] -print(f"Version: {version}") -html_title = " ".join((project, version, "documentation")) +# Import executorch version +# Adopted from PyTorch docs pattern +from executorch import version as et_version # type: ignore[attr-defined] + +executorch_version = str(et_version.__version__) + +# Check if this is a release build from environment variable +# The workflow sets RELEASE=true for tagged releases, RELEASE=false otherwise +# We need to properly parse the string as a boolean (any non-empty string is truthy in Python) +RELEASE = os.environ.get("RELEASE", "false").lower() == "true" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = "main" +# The full version, including alpha/beta/rc tags. +release = "main" + +# Customized html_title here. +# Default is " ".join(project, release, "documentation") if not set +if RELEASE: + # Turn 0.8.0a0+a90e907 into 0.8 + # Note: the release candidates should no longer have the aHASH suffix, but in any + # case we wish to leave only major.minor, even for rc builds. + version = ".".join(executorch_version.split("+")[0].split(".")[:2]) + html_title = " ".join((project, version, "documentation")) + release = version + +switcher_version = "main" if not RELEASE else version + +print(f"executorch_version: {executorch_version}") +print(f"Version: {version}, RELEASE: {RELEASE}") html_baseurl = "https://docs.pytorch.org/executorch/" # needed for sphinx-sitemap sitemap_locales = [None] @@ -176,8 +191,6 @@ # documentation. # -switcher_version = version - html_theme_options = { "logo": { "image_light": "_static/img/et-logo.png", @@ -242,6 +255,7 @@ "display_version": True, } + # 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".