Update doc build to correctly get version (pytorch#15540)

- Update the theme version to to pull the wheel from pypi
- Change how we obtain the version in the CI.
- Updated to properly parse `RELEASE` variable
- Fixed `Makefile` to use `RELEASE=true` instead of `RELEASE=1` for
consistency
- Workflow sets `RELEASE=true` only for tagged releases (e.g., `v1.1.0`)
- Main branch builds with `<meta name="robots" content="noindex">` tag
- Release builds remain indexable by search engines

cc @mergennachin @byjlw

Author: svekars

.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

.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
 

.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
 

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)
 

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".