Sphinx Multiversioning

.github/workflows/build_and_publish_docs.yml

@@ -21,6 +21,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - run: |
+          git remote show origin
+          git checkout dev
+          git checkout master
+          git branch --all
 
       - name: set up python 3.9
         uses: actions/setup-python@v5
@@ -43,6 +50,7 @@ jobs:
           TG_API_HASH: ${{ secrets.TG_API_HASH }}
           TG_BOT_USERNAME: ${{ secrets.TG_BOT_USERNAME }}
         run: |
+          git branch
           python -m poetry run poe docs
 
       - name: remove jekyll theming
@@ -66,7 +74,7 @@ jobs:
           retention-days: 3
 
       - name: deploy website
-        if: ${{ github.ref == 'refs/heads/master' }}
+        if: ${{ github.ref == 'refs/heads/master' || github.ref == 'refs/heads/dev' }}
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages

docs/source/_static/switcher.json

@@ -0,0 +1,12 @@
+[
+    {
+        "name": "stable(master)",
+        "version": "master",
+        "url": "https://zerglev.github.io/dialog_flow_framework/master/index.html"
+    },
+    {
+        "name": "latest(dev)",
+        "version": "dev",
+        "url": "https://zerglev.github.io/dialog_flow_framework/dev/index.html"
+    }
+]

docs/source/conf.py

@@ -10,9 +10,14 @@
 from utils.generate_tutorials import generate_tutorial_links_for_notebook_creation  # noqa: E402
 from utils.link_misc_files import link_misc_files  # noqa: E402
 from utils.regenerate_apiref import regenerate_apiref  # noqa: E402
+from sphinx_polyversion import load
+from sphinx_polyversion.git import GitRef
 
 # -- Project information -----------------------------------------------------
 
+data = load(globals())  # adds variables `current` and `revisions`
+current: GitRef = data['current']
+
 _distribution_metadata = importlib.metadata.metadata('dff')
 
 project = _distribution_metadata["Name"]
@@ -111,6 +116,8 @@
     "css/custom.css",
 ]
 
+switcher_url = "https://raw.githubusercontent.com/ZergLev/dialog_flow_framework/master/docs/source/_static/switcher.json"
+
 # Theme options
 html_theme_options = {
     "header_links_before_dropdown": 5,
@@ -139,6 +146,11 @@
         },
     ],
     "secondary_sidebar_items": ["page-toc", "source-links", "example-links"],
+    "switcher": {
+        "json_url": switcher_url,
+        "version_match": current[0],
+    },
+    "navbar_start": ["navbar-logo", "version-switcher"],
 }
 
 

docs/source/poly.py

@@ -0,0 +1,60 @@
+from pathlib import Path
+from datetime import datetime
+from sphinx_polyversion import *
+from sphinx_polyversion.git import *
+from sphinx_polyversion.pyvenv import Poetry
+from sphinx_polyversion.sphinx import SphinxBuilder
+
+#: Regex matching the branches to build docs for
+BRANCH_REGEX = r"(dev|master|test_branch|test_branch_2|feat/sphinx_multiversion|sphinx_multiversion_test)"
+
+#: Regex matching the tags to build docs for
+TAG_REGEX = r"-"
+
+#: Output dir relative to project root
+OUTPUT_DIR = "docs/build"
+
+#: Source directory
+SOURCE_DIR = "docs/source"
+
+#: Arguments to pass to `poetry install`
+POETRY_ARGS = "--with tutorials,docs --all-extras --no-ansi --no-interaction".split()
+
+#: Arguments to pass to `sphinx-build`
+SPHINX_ARGS = "-b html -W --keep-going -v".split()
+
+#: Mock data used for building local version
+MOCK_DATA = {
+    "revisions": [
+        GitRef("dev", "", "", GitRefType.BRANCH, datetime.fromtimestamp(0)),
+        GitRef("master", "", "", GitRefType.BRANCH, datetime.fromtimestamp(1)),
+        GitRef("test_branch", "", "", GitRefType.BRANCH, datetime.fromtimestamp(2)),
+        GitRef("test_branch_2", "", "", GitRefType.BRANCH, datetime.fromtimestamp(3)),
+        GitRef("feat/sphinx_multiversion", "", "", GitRefType.BRANCH, datetime.fromtimestamp(4)),
+    ],
+    "current": GitRef("local", "", "", GitRefType.BRANCH, datetime.fromtimestamp(5)),
+}
+MOCK = False
+
+# Load overrides read from commandline to global scope
+apply_overrides(globals())
+# Determine repository root directory
+root = Git.root(Path(__file__).parent)
+src = Path(SOURCE_DIR)
+
+# Setup driver and run it
+DefaultDriver(
+    root,
+    OUTPUT_DIR,
+    vcs=Git(
+        branch_regex=BRANCH_REGEX,
+        tag_regex=TAG_REGEX,
+        buffer_size=1 * 10**9,  # 1 GB
+        predicate=file_predicate([src]), # exclude refs without source dir
+    ),
+    builder=SphinxBuilder(src, args=SPHINX_ARGS),
+    env=Poetry.factory(args=POETRY_ARGS),
+    template_dir=root / src / "templates",
+    static_dir=root / src / "static",
+    mock=MOCK_DATA,
+).run(MOCK)