Adding a GHA workflow

.github/workflows/publish.yaml

@@ -0,0 +1,78 @@
+name: Publish
+
+on:
+  push:
+    branches: [ main, develop ]
+    tags: ['v*.*.*']
+
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+  workflow_dispatch:
+
+jobs:
+
+  docs:
+
+    runs-on: ubuntu-20.04
+    # This job only runs for pushed tags
+    #if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+
+    steps:
+
+      - name: Checkout the repo 
+        uses: actions/checkout@v2
+        with:
+          submodules: recursive
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          DEBIAN_FRONTEND=noninteractive sudo apt-get install -y \
+            tree \
+            doxygen \
+            python3-sphinx \
+            graphviz
+          pip install sphinx-multiversion
+
+      - name: Output location
+        run: |
+          export OUTPUT_LOCATION="unknown"
+          echo "Github ref: $GITHUB_REF"
+          if [[ $GITHUB_REF == refs/heads/develop ]]; then
+              echo "Branch is develop"
+              export OUTPUT_LOCATION=develop
+          elif [[ $GITHUB_REF == refs/heads/main ]]; then
+              echo "Branch is main"
+              export OUTPUT_LOCATION=main
+          elif [[ $GITHUB_REF == refs/heads/* ]]; then
+              suffix=${GITHUB_REF#"refs/heads/"}
+              suffix=$(echo $suffix | tr '/' '-')
+              echo "Branch is $GITHUB_REF; directory will be $suffix"
+              export OUTPUT_LOCATION=branches/$suffix
+          elif [[ $GITHUB_REF == refs/tags/* ]]; then
+              suffix=${GITHUB_REF#"refs/tags/"}
+              echo "Tag is $GITHUB_REF; directory will be $suffix"
+              export OUTPUT_LOCATION=tags/$suffix
+          elif [[ $GITHUB_REF == refs/pull/* ]]; then
+              suffix=${GITHUB_HEAD_REF#"refs/heads/"}
+              echo "Branch is $GITHUB_HEAD_REF; directory will be $suffix"
+              export OUTPUT_LOCATION=branches/$suffix
+          fi
+          echo "Output location: $OUTPUT_LOCATION"
+          # Persist the output location in future steps
+          echo "OUTPUT_LOCATION=$OUTPUT_LOCATION" >> $GITHUB_ENV
+
+      - name: Build docs
+        run: |
+          git fetch -a
+          sphinx-multiversion --color source build
+          mv ./build /tmp/build.html
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@4.1.4
+        with:
+          branch: gh-pages-test # The branch the action should deploy to.
+          folder: /tmp/build.html # The folder the action should deploy.
+#          target-folder: ${{ env.OUTPUT_LOCATION }}
+          dry-run: false

Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    = --color
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = sphinx-multiversion
 SOURCEDIR     = source
 BUILDDIR      = build
 

source/_templates/versioning.html

@@ -0,0 +1,14 @@
+{% if versions %}
+<h3>{{ _('Branches') }}</h3>
+<ul>
+  {%- for item in versions.branches %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+<h3>{{ _('Tags') }}</h3>
+<ul>
+  {%- for item in versions.tags %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+{% endif %}

source/conf.py

@@ -40,6 +40,7 @@
 # ones.
 extensions = [
     'sphinx.ext.githubpages',
+    'sphinx_multiversion',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -69,6 +70,13 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+# -- Sphinx-Multiversion configuration ---------------------------------------
+
+smv_tag_whitelist = r'^v\d+\.\d+\.\d+$'            # Include tags like "v2.1.0"
+#smv_tag_whitelist = r'^.*$'                        # Include all tags
+#smv_branch_whitelist = r'^(?!master).*$'           # Include all branches
+smv_branch_whitelist = r'^(main|develop)$'
+smv_remote_whitelist = r'^(origin)$'               # Use branches from origin
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -101,7 +109,15 @@
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
-# html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'globaltoc.html',
+        'relations.html',
+        'sourcelink.html',
+        'searchbox.html',
+        'versioning.html',
+    ],
+}
 
 html_logo = 'DL3Logo.png'
 html_favicon = 'DL3Logo.ico'

source/index.rst

@@ -14,11 +14,6 @@ Welcome to Dripline Controls Guide's documentation!
    logging-data
    process-management
    security
-
-
-.. toctree::
-   :hidden:
-
    command-line-tools
 
 Indices and tables