Fix docs build

Author: coretl

.github/workflows/docs.yml

@@ -7,13 +7,14 @@ on:
 
 jobs:
   build:
+    name: "Docs CI"
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout Source
         uses: actions/checkout@v2
         with:
-          # require all of history to see all tagged versions' docs
+          # require history to get back to last tag for version number of brnaches
           fetch-depth: 0
           submodules: true
 
@@ -22,49 +23,32 @@ jobs:
         with:
           python-version: "3.7"
 
-      - name: Install Packages
-        # Can delete this if you don't use graphviz in your docs
-        run: sudo apt-get install graphviz
-
       - name: Install Python Dependencies
         run: |
           pip install pipenv
           pipenv install --dev --deploy --python $(which python) && pipenv graph
 
-      - name: Deploy index
-        # We pin to the SHA, not the tag, for security reasons.
-        # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: .github/pages
-          keep_files: true
+      - name: Build Docs
+        run: pipenv run docs
 
-      - name: Checkout gh-pages
-        # As we already did a deploy of gh-pages above, it is guaranteed to be there
-        # so check it out so we can selectively build docs below
-        uses: actions/checkout@v2
+      - uses: jungwinter/split@v1
+        id: split
         with:
-          ref: gh-pages
-          path: build/html
-
-      - name: Maybe use sphinx-multiversion
-        # If we are building master or a tag we will publish
-        if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags')
-        # So use the args we normally pass to sphinx-build, but run sphinx-multiversion
-        run: mv $(pipenv --venv)/bin/sphinx-multiversion $(pipenv --venv)/bin/sphinx-build
+          msg: ${{ github.ref }}
+          seperator: /
+          maxsplit: 2
 
-      - name: Build Docs
-        run: pipenv run docs
+      - name: Move to versioned directory
+        # e.g. master or 0.1.2
+        run: mv build/html ".github/pages/${{ steps.split.outputs._2 }}"
 
       - name: Publish Docs to gh-pages
         # Only master and tags are published
-        if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags')
+        if: "${{ github.repository_owner == 'dls-controls' }}"
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
         uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: build/html
+          publish_dir: .github/pages
           keep_files: true
-

Pipfile

@@ -7,8 +7,6 @@ verify_ssl = true
 pytest-cov = "*"
 pytest-flake8 = "*"
 sphinx-rtd-theme = "*"
-# switch to main repo after PR https://github.com/Holzhaus/sphinx-multiversion/pull/60 is merged
-sphinx-multiversion = {editable = true,git = "https://github.com/dls-controls/sphinx-multiversion.git",ref = "only-arg"}
 setuptools-dso = "*"
 aioca = "*"
 pytest-asyncio = "*"

Pipfile.lock

@@ -10,14 +10,36 @@
   <!-- Include Index in the sidebar -->
   <!-- https://stackoverflow.com/a/37843854 -->
   <a href="{{pathto('genindex.html', 1)}}">Index</a>
-  <!-- Include all versions of the docs -->
-  <!-- https://holzhaus.github.io/sphinx-multiversion/master/templates.html -->
-  {% if versions %}
+  <!-- Add versions for selected branches + tags -->
   <p class="caption"><span class="caption-text">Versions</span></p>
-  <ul>
-  {%- for item in versions|reverse %}
-    <li><a href="{{ item.url }}">{{ item.name }}</a></li>
-  {%- endfor %}
-  </ul>
-  {% endif %}
+  <ul id="versions"></ul>
+  <script>
+    // Versions to add, will be filtered by dirs
+    var versions = ['master'];
+    var dirs = new Set();
+    function addVersion(name) {
+      if (dirs.has(name)) {
+        var li = document.createElement("li");
+        var a = document.createElement("a");
+        a.href = 'https://dls-controls.github.io/pythonIoc/' + name;
+        a.innerText = name;
+        li.appendChild(a)
+        document.getElementById('versions').appendChild(li);
+      }
+    }
+    Promise.all([
+      // Find gh-pages directories
+      fetch("https://api.github.com/repos/dls-controls/pythonIoc/contents?ref=gh-pages")
+      .then(response => response.json())
+      .then(data => data.forEach(function(e) {
+        if (e.type == "dir") dirs.add(e.name);
+      })),
+      // Add tags that have pages
+      fetch('https://api.github.com/repos/dls-controls/pythonIoc/tags')
+        .then(response => response.json())
+        .then(data => data.forEach(function(e) {
+          versions.push(e.name);
+        }))
+      ]).then(_ => versions.forEach(addVersion))
+  </script>
 {% endblock %}

docs/_templates/layout.html

@@ -49,8 +49,6 @@
     'sphinx.ext.intersphinx',
     # Add links to source code in API docs
     'sphinx.ext.viewcode',
-    # Add multiple versions of documentation on CI
-    'sphinx_multiversion',
 ]
 
 # If true, Sphinx will warn about all references where the target cannot
@@ -133,14 +131,6 @@
 html_logo = 'images/softioc-logo.svg'
 html_favicon = 'images/softioc-favicon.ico'
 
-# sphinx-multiversion config
-smv_rebuild_tags = False
-smv_tag_whitelist = r'^\d+\.\d+.*$'  # only document tags with form 0.9*
-smv_branch_whitelist = r'^master$'  # only branch to document is master
-smv_outputdir_format = '{ref.name}'
-smv_prefer_remote_refs = False
-smv_remote_whitelist = 'origin|github'
-
 # Common links that should be available on every page
 rst_epilog = """
 .. _epicscorelibs: https://github.com/mdavidsaver/epicscorelibs