From c643d5633aa3705ab56a5529d9a3f738a8be0c93 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Mon, 3 Nov 2025 15:33:36 -0800 Subject: [PATCH 1/7] Update doc build to correctly get version --- .ci/docker/requirements-ci.txt | 3 +-- .github/workflows/doc-build.yml | 21 +++++++++++++-------- docs/source/conf.py | 26 ++++++++++++-------------- 3 files changed, 26 insertions(+), 24 deletions(-) diff --git a/.ci/docker/requirements-ci.txt b/.ci/docker/requirements-ci.txt index d16b91cc7a3..3ce3bda50fa 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 3d24f353e26..69c86143d25 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -49,11 +49,20 @@ jobs: # 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 + # Convert refs/tags/v1.12.0rc3 into 1.12 + # Adopted from https://github.com/pytorch/pytorch/blob/main/.github/workflows/_docs.yml GITHUB_REF=${{ github.ref }} - echo "$GITHUB_REF" - export ET_VERSION_DOCS="${GITHUB_REF}" - echo "$ET_VERSION_DOCS" + echo "GITHUB_REF: $GITHUB_REF" + + if [[ "${GITHUB_REF}" =~ ^refs/tags/v([0-9]+\.[0-9]+) ]]; then + ET_VERSION_DOCS="${BASH_REMATCH[1]}" + else + ET_VERSION_DOCS="main" + fi + + export ET_VERSION_DOCS + echo "ET_VERSION_DOCS: $ET_VERSION_DOCS" set -eux @@ -74,11 +83,7 @@ jobs: cp -rf executorch_android/build/intermediates/java_doc_dir/release/javaDocReleaseGeneration "${RUNNER_DOCS_DIR}/javadoc" cd ../.. - # If it's main branch, add noindex tag to all .html files to exclude from Google Search indexing. - echo "GitHub Ref: ${GITHUB_REF}" - if [[ "${{ github.ref }}" == 'refs/heads/main' ]]; then - find docs/_build/html/ -name "*.html" -print0 | xargs -0 sed -i '//a \ \ '; - fi + # Note: noindex meta tag is automatically added by conf.py for non-stable releases (main, dev versions) cp -rf docs/_build/html/* "${RUNNER_DOCS_DIR}" diff --git a/docs/source/conf.py b/docs/source/conf.py index 78268c8d053..ee648056ca2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -77,22 +77,13 @@ 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) +# The version is already parsed in the workflow (e.g., "1.12" or "main") +# Adopted from PyTorch docs workflow pattern +et_version_docs = os.environ.get("ET_VERSION_DOCS", "main") 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] +# The version variable is used in layout.html and version switcher +version = release = et_version_docs print(f"Version: {version}") html_title = " ".join((project, version, "documentation")) @@ -242,6 +233,13 @@ "display_version": True, } +# Control the noindex meta tag based on version +# Only add noindex for main branch (not stable releases) +if version == "main": + html_meta = { + "robots": "noindex", + } + # 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". From c172f147132bdbd269a92bcce55df23b5eb7846a Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Tue, 4 Nov 2025 14:18:33 -0800 Subject: [PATCH 2/7] Update --- .github/workflows/doc-build.yml | 20 +++++---------- docs/Makefile | 6 +++++ docs/source/conf.py | 44 ++++++++++++++++++++++++--------- 3 files changed, 44 insertions(+), 26 deletions(-) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 69c86143d25..ed3a2ac4c23 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -46,24 +46,16 @@ 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 - # Convert refs/tags/v1.12.0rc3 into 1.12 - # Adopted from https://github.com/pytorch/pytorch/blob/main/.github/workflows/_docs.yml - + # Set RELEASE environment variable for tagged releases GITHUB_REF=${{ github.ref }} - echo "GITHUB_REF: $GITHUB_REF" - - if [[ "${GITHUB_REF}" =~ ^refs/tags/v([0-9]+\.[0-9]+) ]]; then - ET_VERSION_DOCS="${BASH_REMATCH[1]}" + if [[ "${GITHUB_REF}" =~ ^refs/tags/v[0-9]+\.[0-9]+ ]]; then + export RELEASE=true + echo "Building release docs (RELEASE=true)" else - ET_VERSION_DOCS="main" + export RELEASE=false + echo "Building main docs (RELEASE=false)" fi - export ET_VERSION_DOCS - echo "ET_VERSION_DOCS: $ET_VERSION_DOCS" - set -eux # clean up the ${RUNNER_DOCS_DIR} if exists: diff --git a/docs/Makefile b/docs/Makefile index 627358d0387..ae63e723f28 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=1 $(MAKE) html + help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/conf.py b/docs/source/conf.py index ee648056ca2..81265105e2e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -76,16 +76,38 @@ html_favicon = "_static/img/executorch-chip-logo.svg" -# Get ET_VERSION_DOCS during the build. -# The version is already parsed in the workflow (e.g., "1.12" or "main") -# Adopted from PyTorch docs workflow pattern -et_version_docs = os.environ.get("ET_VERSION_DOCS", "main") -print(f"et_version_docs: {et_version_docs}") +# Import executorch version +# Adopted from PyTorch docs pattern +from executorch import version as et_version -# The version variable is used in layout.html and version switcher -version = release = et_version_docs -print(f"Version: {version}") -html_title = " ".join((project, version, "documentation")) +executorch_version = str(et_version.__version__) + +# Check if this is a release build +RELEASE = os.environ.get("RELEASE", False) + +# 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 (" + executorch_version + " )" +# 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] @@ -167,8 +189,6 @@ # documentation. # -switcher_version = version - html_theme_options = { "logo": { "image_light": "_static/img/et-logo.png", @@ -235,7 +255,7 @@ # Control the noindex meta tag based on version # Only add noindex for main branch (not stable releases) -if version == "main": +if not RELEASE: html_meta = { "robots": "noindex", } From 507e99e8240645554f8b0d6fc5c5678bc4bd2b89 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Tue, 4 Nov 2025 16:08:16 -0800 Subject: [PATCH 3/7] Update --- docs/source/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 81265105e2e..edaac126ddb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -82,8 +82,10 @@ executorch_version = str(et_version.__version__) -# Check if this is a release build -RELEASE = os.environ.get("RELEASE", False) +# 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 From 0ef778c0e04e8f5ab71a7ad17b88a56e82c326b3 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Tue, 4 Nov 2025 16:58:38 -0800 Subject: [PATCH 4/7] Fix lint --- .github/workflows/doc-build.yml | 6 +++++- .mypy.ini | 6 ++++++ docs/source/conf.py | 6 ------ 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index ed3a2ac4c23..edb1f6895cc 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -75,7 +75,11 @@ jobs: cp -rf executorch_android/build/intermediates/java_doc_dir/release/javaDocReleaseGeneration "${RUNNER_DOCS_DIR}/javadoc" cd ../.. - # Note: noindex meta tag is automatically added by conf.py for non-stable releases (main, dev versions) + # If it's main branch, add noindex tag to all .html files to exclude from Google Search indexing. + echo "GitHub Ref: ${GITHUB_REF}" + if [[ "${{ github.ref }}" == 'refs/heads/main' ]]; then + find docs/_build/html/ -name "*.html" -print0 | xargs -0 sed -i '//a \ \ '; + fi cp -rf docs/_build/html/* "${RUNNER_DOCS_DIR}" diff --git a/.mypy.ini b/.mypy.ini index baea2efefa9..e01392a0dfd 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/source/conf.py b/docs/source/conf.py index edaac126ddb..f694fd517eb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -255,12 +255,6 @@ "display_version": True, } -# Control the noindex meta tag based on version -# Only add noindex for main branch (not stable releases) -if not RELEASE: - html_meta = { - "robots": "noindex", - } # 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, From db809349bf7ea88dd62dd2d164d8a09f7efef1f4 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Tue, 4 Nov 2025 19:27:54 -0800 Subject: [PATCH 5/7] Update --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index f694fd517eb..8a772403fc8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -78,7 +78,7 @@ # Import executorch version # Adopted from PyTorch docs pattern -from executorch import version as et_version +from executorch import version as et_version # type: ignore[attr-defined] executorch_version = str(et_version.__version__) From c86b8d8ecab1890ec794e2664dd9b696591f70e2 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 5 Nov 2025 11:16:11 -0800 Subject: [PATCH 6/7] Update --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index ae63e723f28..c4f5e571ff8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,7 +17,7 @@ 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=1 $(MAKE) html + RELEASE=true $(MAKE) html help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From e213d41baf55470c3a88c62a88be30d89c3b8128 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Thu, 6 Nov 2025 08:54:12 -0800 Subject: [PATCH 7/7] Update --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8a772403fc8..f69fc243255 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -92,7 +92,7 @@ # built documents. # # The short X.Y version. -version = "main (" + executorch_version + " )" +version = "main" # The full version, including alpha/beta/rc tags. release = "main"