Use sphinx-multiversion to support documentation for multiple versions (

#349) * Use sphinx-multiversion to support documentation for multiple versions * Change message when seeing development version * Use only-arg branch of sphinx-multiversion to avoid re-writing old documentation * Add docs.yml to automatically generate and publish docs
bambinos · May 15, 2021 · 963b1bb · 963b1bb
1 parent a273d20
commit 963b1bb
Show file tree

Hide file tree

Showing 7 changed files with 172 additions and 7 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,52 @@
+
+name: Publish documentation
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+
+    # Example of using a custom build-command.
+    - uses: ammaraskar/sphinx-action@master
+      with:
+        pre-build-command: python -m pip install -r requirements.txt -r requirements-dev.txt
+        build-command: "sphinx-multiversion . ./_build/html"
+        docs-folder: "docs/"
+
+    # Great extra actions to compose with:
+    # Create an artifact of the html output.
+    - uses: actions/upload-artifact@v1
+      with:
+        name: DocumentationHTML
+        path: docs/_build/html/
+
+    # Publish built docs to gh-pages branch.
+    # ===============================
+    - name: Commit documentation changes
+      run: |
+        git clone https://github.com/bambinos/bambi.git --branch gh-pages --single-branch gh-pages
+        cp docs/_assets/gh-pages-redirect.html docs/_build/index.html
+        cp -r docs/_build/html/* gh-pages/
+        cd gh-pages
+        touch .nojekyll
+        git config --local user.email "[email protected]"
+        git config --local user.name "GitHub Action"
+        git add .
+        git commit -m "Update documentation" -a || true
+        # The above command will fail if no changes were present, so we ignore
+        # that.
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        branch: gh-pages
+        directory: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+    # ===============================
diff --git a/docs/Makefile b/docs/Makefile
@@ -2,17 +2,24 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXOPTS    = # "-W" treats warnings as errors
+SPHINXBUILD   ?= sphinx-multiversion
 SOURCEDIR     = .
-BUILDDIR      = _build
+BUILDDIR      ?= _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
 
+clean:
+	rm -rf $(BUILDDIR)/*
+
+# For local build
+local:
+	sphinx-build "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

diff --git a/docs/_assets/gh-pages-redirect.html b/docs/_assets/gh-pages-redirect.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to https://bambinos.github.io/bambi/master/</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./master/index.html">
+    <link rel="canonical" href="https://bambinos.github.io/bambi/">
+  </head>
+</html>
diff --git a/docs/_templates/versioning.html b/docs/_templates/versioning.html
@@ -0,0 +1,66 @@
+{% if versions %}
+
+  {% if current_version != versions.tags[-1] and current_version != versions.branches[0] %}
+  <p style="margin-top: 1em; margin-bottom: 0;">
+    <strong>
+    You're reading an old version of this documentation (v. {{current_version.name}}).<br>
+    If you want up-to-date information, please have a look at <a href="{{ vpathto(versions.tags[-1].name) }}">latest</a>.
+  </strong>
+  </p>
+  {% endif %}
+
+  {% if current_version == versions.branches[0] %}
+  <p style="margin-top: 1em; margin-bottom: 0;">
+  <strong>
+    You're reading the documentation for a development version ({{current_version.name}}).<br>
+    For the latest released version, please have a look at <a href="{{ vpathto(versions.tags[-1].name) }}">latest</a>.
+  </strong>
+  </p>
+  {% endif %}
+
+<nav class="bd-links" id="bd-docs-nav" aria-label="Versions navigation">
+    <div class="bd-toc-item active">
+        <ul class="current nav bd-sidenav">
+        <li class="toctree-l1 has-children">
+            <p class="caption"><span class="caption-text">Version</span></p>
+            <input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox">
+            <label for="toctree-checkbox-1"> <i class="fas fa-chevron-down"></i></label>
+
+            <ul>
+
+                {%- for item in versions.branches %}
+                  {% if item == current_version %}
+                  <li class="toctree-l2 current active"><a href="{{ item.url }}"> Development </a></li>
+                  {% else %}
+                  <li><a href="{{ item.url }}"> Development </a></li>
+                  {% endif %}
+                {%- endfor %}
+
+                {%- for item in versions.tags[::-1] %}
+
+                {% if item == current_version %}
+
+                  {% if loop.first %}
+                    <li class="toctree-l2 current active"><a href="{{ item.url }}">{{ item.name }} (latest)</a></li>
+                  {% else %}
+                    <li class="toctree-l2 current active"><a href="{{ item.url }}">{{ item.name }}</a></li>
+                  {% endif %}
+
+                {% else %}
+
+                  {% if loop.first %}
+                    <li><a href="{{ item.url }}">{{ item.name }} (latest)</a></li>
+                  {% else %}
+                    <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+                  {% endif %}
+
+                {% endif %}
+                {%- endfor %}
+
+            </ul>
+        </li>
+        </ul>
+    </div>
+  </nav>
+
+{% endif %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -45,14 +45,19 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'sphinx.ext.mathjax',
-    'nbsphinx'
+    'nbsphinx',
+    'sphinx_multiversion'
 ]
 
 nbsphinx_execute = "never"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+html_sidebars = {
+    "**": ["searchbox.html", "versioning.html"]
+}
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -84,13 +89,18 @@
 # a list of builtin themes.
 #
 html_theme = 'pydata_sphinx_theme'
-# html_theme_path = [sphinx_alabaster_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
+
+# https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#remove-the-sidebar-from-some-pages
+
 html_theme_options = {
+    "collapse_navigation": True,
+    "show_toc_level": 2,
+    "navigation_depth": 4,
+    "search_bar_text": "Search the docs...",
     "icon_links": [
         {
             "name": "GitHub",
@@ -120,6 +130,25 @@
 #
 # html_sidebars = {}
 
+# Whitelist pattern for remotes (set to None to use local branches only)
+smv_remote_whitelist = r"^origin$"
+
+# Whitelist pattern for branches (set to None to ignore all branches)
+smv_branch_whitelist = r"^master$"
+
+# Tags are released
+smv_released_pattern = r'^refs/tags/.*$'
+
+# Tags like 0.0.1, 0.5.1 are kept
+# smv_tag_whitelist = r'^\d+\.\d+\.\d+S'
+
+# sphinx-multiversion options
+smv_rebuild_tags = False
+smv_tag_whitelist = r'^\d+\.\d+.\d+$'
+#smv_branch_whitelist = r'master'
+#smv_released_pattern = r'^tags/*$'
+
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -197,3 +226,4 @@
 
 
 # -- Extension configuration -------------------------------------------------
+# https://svn.python.org/projects/external/Jinja-1.1/docs/build/designerdoc.html
diff --git a/docs/index.rst b/docs/index.rst
@@ -17,7 +17,7 @@ BAyesian Model-Building Interface (Bambi) in Python
     :target: https://travis-ci.org/bambinos/bambi
 
 .. |Coverage| image:: https://codecov.io/gh/bambinos/bambi/branch/master/graph/badge.svg?token=ZqH0KCLKAE
-    :target: https://coveralls.io/github/bambinos/bambi
+    :target: https://codecov.io/gh/bambinos/bambi
 
 .. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/ambv/black

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -6,4 +6,5 @@ seaborn>=0.9.0
 sphinx>=1.8
 nbsphinx>=0.4.2
 pydata-sphinx-theme>=0.6.3
+git+https://github.com/dls-controls/sphinx-multiversion.git@only-arg
 black>=20.8b1