docs: use sphinx-multiversion for version selector

anand-bala · Oct 13, 2023 · 2ed91f6 · 2ed91f6
1 parent a7431ce
commit 2ed91f6
Show file tree

Hide file tree

Showing 6 changed files with 58 additions and 48 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -101,37 +101,10 @@ jobs:
       - name: Build Python package
         run: maturin develop --release --manifest-path pyargus/Cargo.toml
       - name: Build HTML docs
-        run: sphinx-build -b html docs docs/_build/
+        run: sphinx-multiversion -b html docs _site
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         if: github.ref == 'refs/heads/dev' || startsWith(github.ref, 'refs/tags/')
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/_build/
-          destination_dir: ${{ github.ref_name }}
-      - uses: actions/checkout@v4
-        with:
-          ref: 'gh-pages'
-      - name: Install tree
-        run: |
-          sudo apt-get update -y
-          sudo apt-get install -y tree
-      - run: |
-          tree -H '.' \
-              -L 1 \
-              --noreport \
-              --dirsfirst \
-              --charset utf-8 \
-              --ignore-case \
-              --timefmt '%d-%b-%Y %H:%M' \
-              -I "index.html" \
-              -T 'Argus Python Documentation versions' \
-              -s -D \
-              -o index.html
-          git config user.name github-actions
-          git config user.email [email protected]
-          git add .
-          if [[ ! $(git diff --quiet) ]]; then
-            git commit -m "update index.html"
-            git push
-          fi
+          publish_dir: _site/
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+### Docs ###
+/_site/
 ### Lcov ###
 
 *.lcov

diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html
@@ -0,0 +1,30 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <details open="true">
+    <summary>
+      <span class="fa fa-book"> Current Version</span>
+      {{ current_version.name }}
+      <span class="fa fa-caret-down"></span>
+    </summary>
+
+    <div class="rst-other-versions">
+      {%- if versions.tags %}
+      <dl>
+        <dt>Tags</dt>
+        {%- for item in versions.tags %}
+        <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+        {%- endfor %}
+      </dl>
+      {%- endif %}
+      {%- if versions.branches %}
+      <dl>
+        <dt>Branches</dt>
+        {%- for item in versions.branches %}
+        <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+        {%- endfor %}
+      </dl>
+      {%- endif %}
+    </div>
+  </details>
+</div>
+{%- endif %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,29 +27,29 @@
     "myst_parser",
     "sphinx_copybutton",
     "sphinx.ext.inheritance_diagram",
+    "sphinx_multiversion",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-html_theme = "pydata_sphinx_theme"
+html_theme = "furo"
 html_static_path = ["_static"]
 html_theme_options = {
-    "use_edit_page_button": True,
-    "github_url": "https://github.com/anand-bala/argus",
-    "switcher": {
-        "json_url": "https://anand-bala.github.io/argus/dev/_static/switcher.json",
-        "version_match": version,
-    },
-    "check_switcher": False,
-    "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
-    "navbar_center": ["version-switcher", "navbar-nav"],
+    "source_repository": "https://github.com/anand-bala/argus/",
+    "source_branch": "dev",
+    "source_directory": "docs/",
 }
-html_context = {
-    "github_user": "anand-bala",
-    "github_repo": "argus",
-    "github_version": "v0.1.1",
-    "doc_path": "docs",
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+        "versions.html",
+    ]
 }
 
 source_suffix = {
@@ -58,6 +58,10 @@
     ".md": "markdown",
 }
 
+
+# Whitelist pattern for branches (set to None to ignore all branches)
+smv_branch_whitelist = r"^dev$"
+
 autoapi_dirs = ["../pyargus/argus"]
 autoapi_root = "api"
 

diff --git a/environment.yaml b/environment.yaml
@@ -19,10 +19,11 @@ dependencies:
   - lark # hypothesis[lark]
   - pip
   - sphinx
-  - pydata-sphinx-theme
+  - furo
   - sphinx-copybutton
   - myst-parser
   - pip:
       - sphinx-autoapi
+      - sphinx-multiversion
 
 category: dev
diff --git a/noxfile.py b/noxfile.py
@@ -41,14 +41,14 @@ def dev(session: nox.Session):
 def docs(session: nox.Session):
     session.conda_install(
         "sphinx",
-        "pydata-sphinx-theme",
+        "furo",
         "sphinx-copybutton",
         "myst-parser",
     )
-    session.install("sphinx-autoapi")
+    session.install("sphinx-autoapi", "sphinx-multiversion")
     with session.chdir(CURRENT_DIR / "pyargus"):
         session.install("-e", ".")
-    session.run("sphinx-build", "-b", "html", "docs", "docs/_build/html")
+    session.run("sphinx-multiversion", "-b", "html", "docs", "_site")
 
 
 @nox.session(tags=["style", "fix", "rust"], python=False)