Doc versioning (#84)

* test versioning

* publish doc

* publish doc

* fix make

* fix make

* fetch tags only

* fetch all

* add versions

* add versions

* test

* test

* upd ci

* upd ci

* upd ci

* upd ci

* upd ci

* change dir

* build tags

* fix cp

* update url

* remove sphinx multiversion

* fix url

* upd json

* fix static paths

* static url

* use again sphinx-multiversion

* upd

* upd

* upd dir name

* add ifs

* uncomment

* lint

Author: Samoed

.github/workflows/build-docs.yaml

@@ -1,9 +1,12 @@
-name: Build and publish docs
+name: Build and Publish Multi-Version Docs
 
 on:
   push:
     branches:
-    - dev
+      - dev
+  release:
+    types:
+      - published
   pull_request:
     branches:
       - dev
@@ -17,13 +20,18 @@ permissions:
   contents: write
 
 jobs:
-  publish:
-    name: build and publish docs
+  build-docs:
+    name: Build Documentation
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
 
-      - name: set up python 3.10
+      - name: Set up Python 3.10
         uses: actions/setup-python@v5
         with:
           python-version: "3.10"
@@ -36,37 +44,30 @@ jobs:
         run: |
           sudo apt install pandoc
 
-      - name: install dependencies
+      - name: Install dependencies
         run: |
           poetry install --with docs
 
-      - name: Test documentation
+      - name: Run tests
         run: |
+          echo "Testing documentation build..."
           make test-docs
 
-      - name: build documentation
+      - name: Build documentation
+        if: ${{ github.ref == 'refs/heads/dev' }}
         run: |
           make docs
 
-      - name: save branch name without slashes
-        env:
-          BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
+      - name: build multiversion documentation
+        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
         run: |
-          BRANCH_NAME=${{ env.BRANCH_NAME }}
-          BRANCH_NAME=${BRANCH_NAME////_}
-          echo BRANCH_NAME=${BRANCH_NAME} >> $GITHUB_ENV
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ format('github-pages-for-branch-{0}', env.BRANCH_NAME) }}
-          path: docs/build/
-          retention-days: 3
+          make multi-version-docs
 
       - name: Deploy to GitHub Pages
-        uses: JamesIves/[email protected]
-        if: ${{ github.ref == 'refs/heads/dev' }}
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
         with:
-          branch: gh-pages
-          folder: docs/build/html/
-          single-commit: True
+          github_token: ${{ github.token }}
+          publish_dir: docs/build/html/versions
+          destination_dir: versions
+          keep_files: true

.github/workflows/ruff.yml

@@ -5,4 +5,4 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/ruff-action@v1
+      - uses: astral-sh/ruff-action@v1

Makefile

@@ -31,13 +31,17 @@ docs:
 	$(poetry) python -m sphinx build -b html docs/source docs/build/html
 
 .PHONY: test-docs
-test-docs: docs
+test-docs:
 	$(poetry) python -m sphinx build -b doctest docs/source docs/build/html
 
 .PHONY: serve-docs
 serve-docs: docs
 	$(poetry) python -m http.server -d docs/build/html 8333
 
+.PHONY: multi-version-docs
+multi-version-docs:
+	$(poetry) sphinx-multiversion docs/source docs/build/html
+
 .PHONY: clean-docs
 clean-docs:
 	rm -rf docs/build

autointent/_pipeline/_pipeline.py

@@ -135,7 +135,8 @@ def fit(self, dataset: Dataset, force_multilabel: bool = False) -> Context:
         predictions = self.predict(context.data_handler.test_utterances())
         for metric_name, metric in PREDICTION_METRICS_MULTILABEL.items():
             context.optimization_info.pipeline_metrics[metric_name] = metric(
-                context.data_handler.test_labels(), predictions,
+                context.data_handler.test_labels(),
+                predictions,
             )
 
         return context

docs/_static/versions.json

@@ -0,0 +1,12 @@
+[
+    {
+        "name": "v0.0.1 (stable)",
+        "version": "v0.0.1",
+        "url": "https://deeppavlov.github.io/AutoIntent/versions/v0.0.1/",
+        "preferred": true
+    },
+    {
+        "version": "dev (dev)",
+        "url": "https://deeppavlov.github.io/AutoIntent/versions/dev/"
+    }
+]

docs/source/conf.py

@@ -5,17 +5,19 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 import os
 import sys
+from importlib.metadata import version
 from pathlib import Path
 
+from docs.source.docs_utils.tutorials import generate_tutorial_links_for_notebook_creation
+
 conf_dir = os.path.dirname(os.path.abspath(__file__))  # noqa: PTH100, PTH120
 
 sys.path.insert(0, conf_dir)
 
 from docs_utils.skip_members import skip_member  # noqa: E402
-from docs_utils.tutorials import generate_tutorial_links_for_notebook_creation  # noqa: E402
+from docs_utils.versions_generator import generate_versions_json  # noqa: E402
 
 project = "AutoIntent"
 copyright = "2024, DeepPavlov"
@@ -44,6 +46,7 @@
     "sphinx_copybutton",
     "nbsphinx",
     "sphinx.ext.intersphinx",
+    "sphinx_multiversion",
 ]
 
 templates_path = ["_templates"]
@@ -81,12 +84,16 @@
 
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["../_static"]
+version = version("autointent").replace("dev", "")  # may differ
+
+BASE_URL = "https://deeppavlov.github.io/AutoIntent/versions"
+BASE_STATIC_URL = f"{BASE_URL}/dev/_static"
 
 html_theme_options = {
     "logo": {
         "text": "AutoIntent",
-        "image_light": "../_static/logo-light.svg",
-        "image_dark": "../_static/logo-dark.svg",
+        "image_light": f"{BASE_STATIC_URL}/logo-light.svg",
+        "image_dark": f"{BASE_STATIC_URL}/logo-dark.svg",
     },
     "icon_links": [
         {
@@ -98,14 +105,19 @@
         {
             "name": "HuggingFace",
             "url": "https://huggingface.co/AutoIntent",
-            "icon": "../_static/hf-logo.svg",
+            "icon": f"{BASE_STATIC_URL}/hf-logo.svg",
             "type": "local",
         },
     ],
+    "switcher": {
+        "json_url": f"{BASE_STATIC_URL}/versions.json",
+        "version_match": version,
+    },
+    "navbar_start": ["navbar-logo", "version-switcher"],
     "show_toc_level": 3,
 }
 
-html_favicon = "../_static/logo-white.svg"
+html_favicon = f"{BASE_STATIC_URL}/logo-white.svg"
 html_show_sourcelink = False
 
 toc_object_entries_show_parents = "hide"
@@ -133,8 +145,28 @@
 
 mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
 
+# sphinx_multiversion
+# Whitelist for tags matching v1.0.0, v2.1.0 format
+# smv_tag_whitelist = r'^v\d+\.\d+\.\d+$'
+smv_tag_whitelist = r"^.*$"
+
+# Whitelist for the dev branch
+smv_branch_whitelist = r"^dev$"
+
+# Output format (keeping your current format)
+smv_outputdir_format = "versions/{ref.name}"
+
+# Include both tags and dev branch as released
+smv_released_pattern = r"^(refs/tags/.*|refs/heads/dev)$"
+
+smv_remote_whitelist = r"^(origin|upstream)$"  # Use branches from origin and upstream
+
+repo_root = Path(__file__).resolve().parents[2]  # if conf.py is in docs/
+
 
 def setup(app) -> None:  # noqa: ANN001
+    generate_versions_json(repo_root, BASE_URL)
+
     generate_tutorial_links_for_notebook_creation(
         include=[
             (

docs/source/docs_utils/versions_generator.py

@@ -0,0 +1,69 @@
+import json
+import logging
+import os
+import re
+import subprocess
+from pathlib import Path
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def get_sorted_versions(repo_root: Path, base_url: str) -> list[dict]:
+    os.chdir(repo_root)
+    # Fetch tags and branches
+    tags_output = subprocess.check_output(["git", "tag"], text=True).strip().split("\n")  # noqa: S603, S607
+    tag_regex = re.compile(r"^v\d+\.\d+\.\d+$")  # Matches tags like v0.0.1
+    tags = [tag for tag in tags_output if tag_regex.match(tag)]
+
+    sorted_tags = sorted(tags, reverse=True)
+
+    logger.info("sorted_tags: %s", sorted_tags)
+
+    # Prepare versions list (similar to previous implementation)
+    versions = []
+
+    if sorted_tags:
+        versions.append(
+            {
+                "name": f"{sorted_tags[0]} (stable)",
+                "version": sorted_tags[0],
+                "url": f"{base_url}/{sorted_tags[0]}/",
+                "preferred": True,
+            }
+        )
+
+    for tag in sorted_tags[1:]:
+        versions.append({"version": tag, "url": f"{base_url}/{tag}/"})  # noqa: PERF401
+
+    # Get branches
+    branches_output = subprocess.check_output(["git", "branch", "-r"], text=True).strip().split("\n")  # noqa: S603, S607
+    dev_branches = [
+        branch.strip().split("/")[-1] for branch in branches_output if "origin/dev" in branch and "HEAD" not in branch
+    ]
+    logger.info("dev_branches: %s", dev_branches)
+
+    for branch in dev_branches:
+        versions.append({"version": f"{branch} (dev)", "url": f"{base_url}/{branch}/"})  # noqa: PERF401
+
+    return versions
+
+
+def generate_versions_json(repo_root: Path, base_url: str) -> None:
+    """
+    Sphinx extension to generate versions.json during documentation build.
+    """
+    # Only generate if no exception occurred
+    # Ensure _static directory exists
+    static_dir = repo_root / "docs" / "_static"
+    static_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate and write versions JSON
+    versions = get_sorted_versions(repo_root, base_url)
+    versions_path = static_dir / "versions.json"
+
+    # Always generate a JSON, even if empty
+    with versions_path.open("w") as f:
+        json.dump(versions, f, indent=4)
+
+    logger.info("versions.json generated at %s", versions_path)

pyproject.toml

@@ -95,6 +95,7 @@ sphinx-autodoc-typehints = "^2.5.0"
 sphinx-copybutton = "^0.5.2"
 sphinx-autoapi = "^3.3.3"
 ipykernel = "^6.29.5"
+sphinx-multiversion = "^0.2.4"
 
 [tool.poetry.scripts]
 "autointent" = "autointent._pipeline._cli_endpoint:optimize"

tests/context/datahandler/test_data_handler.py

@@ -129,7 +129,7 @@ def test_sample_validation(label):
             "validation_1": mock_split(),
             "test": mock_split(),
         },
-    ]
+    ],
 )
 def test_dataset_initialization(mapping):
     dataset = Dataset.from_dict(mapping)
@@ -151,8 +151,8 @@ def test_dataset_initialization(mapping):
         {"train": mock_split(), "validation": mock_split(), "validation_0": mock_split()},
         {"train": mock_split(), "validation": mock_split(), "validation_1": mock_split()},
         {"train": mock_split(), "validation": mock_split(), "validation_0": mock_split(), "validation_1": mock_split()},
-        {"train": mock_split(), "oos": mock_split()}
-    ]
+        {"train": mock_split(), "oos": mock_split()},
+    ],
 )
 def test_dataset_validation(mapping):
     with pytest.raises(ValueError):
@@ -169,7 +169,7 @@ def test_dataset_validation(mapping):
             "test": [{"utterance": "Hello!", "label": 0}],
         },
         {"train": [{"utterance": "Hello!"}]},
-    ]
+    ],
 )
 def test_intents_validation(mapping):
     with pytest.raises(ValueError):