Merge pull request #31 from DiamondLightSource/dev

New docs theme

.github/CONTRIBUTING.rst

@@ -0,0 +1,35 @@
+Contributing to the project
+===========================
+
+Contributions and issues are most welcome! All issues and pull requests are
+handled through GitHub_. Also, please check for any existing issues before
+filing a new one. If you have a great idea but it involves big changes, please
+file a ticket before making a pull request! We want to make sure you don't spend
+your time coding something that might not fit the scope of the project.
+
+.. _GitHub: https://github.com/DiamondLightSource/python3-pip-skeleton-cli/issues
+
+Issue or Discussion?
+--------------------
+
+Github also offers discussions_ as a place to ask questions and share ideas. If
+your issue is open ended and it is not obvious when it can be "closed", please
+raise it as a discussion instead.
+
+.. _discussions: https://github.com/DiamondLightSource/python3-pip-skeleton-cli/discussions
+
+Code coverage
+-------------
+
+While 100% code coverage does not make a library bug-free, it significantly
+reduces the number of easily caught bugs! Please make sure coverage remains the
+same or is improved by a pull request!
+
+Developer guide
+---------------
+
+The `Developer Guide`_ contains information on setting up a development
+environment, running the tests and what standards the code and documentation
+should follow.
+
+.. _Developer Guide: https://diamondlightsource.github.io/python3-pip-skeleton-cli/main/developer/how-to/contribute.html

.github/pages/make_switcher.py

@@ -0,0 +1,99 @@
+import json
+import logging
+from argparse import ArgumentParser
+from pathlib import Path
+from subprocess import CalledProcessError, check_output
+from typing import List, Optional
+
+
+def report_output(stdout: bytes, label: str) -> List[str]:
+    ret = stdout.decode().strip().split("\n")
+    print(f"{label}: {ret}")
+    return ret
+
+
+def get_branch_contents(ref: str) -> List[str]:
+    """Get the list of directories in a branch."""
+    stdout = check_output(["git", "ls-tree", "-d", "--name-only", ref])
+    return report_output(stdout, "Branch contents")
+
+
+def get_sorted_tags_list() -> List[str]:
+    """Get a list of sorted tags in descending order from the repository."""
+    stdout = check_output(["git", "tag", "-l", "--sort=-v:refname"])
+    return report_output(stdout, "Tags list")
+
+
+def get_versions(ref: str, add: Optional[str], remove: Optional[str]) -> List[str]:
+    """Generate the file containing the list of all GitHub Pages builds."""
+    # Get the directories (i.e. builds) from the GitHub Pages branch
+    try:
+        builds = set(get_branch_contents(ref))
+    except CalledProcessError:
+        builds = set()
+        logging.warning(f"Cannot get {ref} contents")
+
+    # Add and remove from the list of builds
+    if add:
+        builds.add(add)
+    if remove:
+        assert remove in builds, f"Build '{remove}' not in {sorted(builds)}"
+        builds.remove(remove)
+
+    # Get a sorted list of tags
+    tags = get_sorted_tags_list()
+
+    # Make the sorted versions list from main branches and tags
+    versions: List[str] = []
+    for version in ["master", "main"] + tags:
+        if version in builds:
+            versions.append(version)
+            builds.remove(version)
+
+    # Add in anything that is left to the bottom
+    versions += sorted(builds)
+    print(f"Sorted versions: {versions}")
+    return versions
+
+
+def write_json(path: Path, repository: str, versions: str):
+    org, repo_name = repository.split("/")
+    struct = [
+        dict(name=version, url=f"https://{org}.github.io/{repo_name}/{version}/")
+        for version in versions
+    ]
+    text = json.dumps(struct, indent=2)
+    print(f"JSON switcher:\n{text}")
+    path.write_text(text)
+
+
+def main(args=None):
+    parser = ArgumentParser(
+        description="Make a versions.txt file from gh-pages directories"
+    )
+    parser.add_argument(
+        "--add",
+        help="Add this directory to the list of existing directories",
+    )
+    parser.add_argument(
+        "--remove",
+        help="Remove this directory from the list of existing directories",
+    )
+    parser.add_argument(
+        "repository",
+        help="The GitHub org and repository name: ORG/REPO",
+    )
+    parser.add_argument(
+        "output",
+        type=Path,
+        help="Path of write switcher.json to",
+    )
+    args = parser.parse_args(args)
+
+    # Write the versions file
+    versions = get_versions("origin/gh-pages", args.add, args.remove)
+    write_json(args.output, args.repository, versions)
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/code.yml

@@ -139,7 +139,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: dist
-          path: dist/*
+          path: dist
 
   sdist:
     needs: container
@@ -171,8 +171,7 @@ jobs:
         uses: softprops/action-gh-release@1e07f4398721186383de40550babbdf2b84acfc5 # v0.1.14
         with:
           prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
-          files: |
-            dist/*
+          files: dist/*
           generate_release_notes: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/docs.yml

@@ -43,10 +43,10 @@ jobs:
 
       - name: Move to versioned directory
         # e.g. main or 0.1.2
-        run: mv build/html ".github/pages/${GITHUB_REF##*/}"
+        run: mv build/html ".github/pages/${{ github.ref_name }}"
 
-      - name: Write versions.txt
-        run: sphinx_rtd_theme_github_versions .github/pages
+      - name: Write switcher.json
+        run: python .github/pages/make_switcher.py --add "${{ github.ref_name }}" ${{ github.repository }} .github/pages/switcher.json
 
       - name: Publish Docs to gh-pages
         if: github.event_name == 'push'

.github/workflows/docs_clean.yml

@@ -32,10 +32,9 @@ jobs:
 
       - name: update index and push changes
         run: |
-          echo removing redundant documentation version ${{ env.remove_me }}
           rm -r ${{ env.remove_me }}
-          sed -i /${{ env.remove_me }}/d versions.txt
+          python make_switcher.py --remove ${{ env.remove_me }} ${{ github.repository }} switcher.json
           git config --global user.name 'GitHub Actions Docs Cleanup CI'
-          git config --global user.email 'GithubActionsCleanup@users.noreply.github.com'
-          git commit -am"removing redundant docs version ${{ env.remove_me }}" 
+          git config --global user.email '[email protected]'
+          git commit -am"removing redundant docs version ${{ env.remove_me }}"
           git push

.vscode/extensions.json

@@ -1,8 +1,8 @@
 {
     "recommendations": [
-        "ms-vscode-remote.remote-containers"
+        "ms-vscode-remote.remote-containers",
         "ms-python.vscode-pylance",
         "ms-python.python",
         "ryanluker.vscode-coverage-gutters"
     ]
-}
+}

Dockerfile

@@ -1,6 +1,6 @@
 # This file is for use as a devcontainer and a runtime container
-# 
-# The devcontainer should use the build target and run as root with podman 
+#
+# The devcontainer should use the build target and run as root with podman
 # or docker with user namespaces.
 #
 FROM python:3.10 as build
@@ -11,6 +11,7 @@ RUN apt-get update && apt-get upgrade -y && \
     build-essential \
     busybox \
     git \
+    graphviz \
     net-tools \
     vim \
     && rm -rf /var/lib/apt/lists/* \
@@ -26,6 +27,7 @@ RUN cd /project && \
 
 RUN python -m venv /venv
 ENV PATH=/venv/bin:$PATH
+ENV TOX_DIRECT=1
 
 RUN cd /project && \
     pip install --upgrade pip && \