Migrate docs from skeleton

DiamondLightSource · Jan 22, 2024 · bf4eb02 · bf4eb02
1 parent ecdfff3
commit bf4eb02
Show file tree

Hide file tree

Showing 58 changed files with 2,214 additions and 15 deletions.
diff --git a/.github/CONTRIBUTING.rst b/.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
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
diff --git a/.github/pages/index.html b/.github/pages/index.html
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>Redirecting to main branch</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+    <link rel="canonical" href="main/index.html">
+</head>
+
+</html>
diff --git a/.github/pages/make_switcher.py b/.github/pages/make_switcher.py
@@ -0,0 +1,92 @@
+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]) -> 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)
+
+    # 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(version=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, encoding="utf-8")
+
+
+def main(args=None):
+    parser = ArgumentParser(
+        description="Make a versions.json file from gh-pages directories"
+    )
+    parser.add_argument(
+        "--add",
+        help="Add this directory to 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)
+    write_json(args.output, args.repository, versions)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/workflows/_check.yml b/.github/workflows/_check.yml
@@ -0,0 +1,27 @@
+on:
+  workflow_call:
+    outputs:
+      branch-pr:
+        description: The PR number if the branch is in one
+        value: ${{ jobs.pr.outputs.branch-pr }}
+
+jobs:
+  pr:
+    runs-on: "ubuntu-latest"
+    outputs:
+      branch-pr: ${{ steps.script.outputs.result }}
+    steps:
+      - uses: actions/github-script@v7
+        id: script
+        if: github.event_name == 'push'
+        with:
+          script: |
+            const prs = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              head: context.repo.owner + ':${{ github.ref_name }}'
+            })
+            if (prs.data.length) {
+              console.log(`::notice ::Skipping CI on branch push as it is already run in PR #${prs.data[0]["number"]}`)
+              return prs.data[0]["number"]
+            }
diff --git a/.github/workflows/_docs.yml b/.github/workflows/_docs.yml
@@ -0,0 +1,52 @@
+on:
+  workflow_call:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install system packages
+        run: sudo apt-get install graphviz
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install python packages
+        uses: pip install -c requirements.txt
+
+      - name: Build docs
+        run: sphinx-build -EW --keep-going -T docs build/html
+
+      - name: Remove environment.pickle
+        run: rm build/html/.doctrees/environment.pickle
+
+      - name: Move to versioned directory
+        run: mv build/html build/${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}
+
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: build
+
+      - name: Add other static pages files
+        run: cp .github/pages/* build
+
+      - name: Write switcher.json
+        run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} build/switcher.json
+
+      - name: Publish Docs to gh-pages
+        if: github.event_name == 'push' && github.actor != 'dependabot[bot]'
+        # We pin to the SHA, not the tag, for security reasons.
+        # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+        uses: peaceiris/actions-gh-pages@bd8c6b06eba6b3d25d72b7a1767993c0aeee42e7 # v3.9.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build
+          keep_files: true
diff --git a/.github/workflows/_release.yml b/.github/workflows/_release.yml
@@ -0,0 +1,33 @@
+on:
+  workflow_call:
+
+jobs:
+  artifacts:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+
+      - name: Prepare release files
+        run: |
+          if [ -d docs ]; then
+            cd docs && zip -r docs.zip *
+            echo 'DOCS=docs/docs.zip' >> $GITHUB_ENV
+          fi
+          if [ -d dist ]; then
+            echo 'DIST=dist/*' >> $GITHUB_ENV
+          fi
+
+      - name: Create GitHub Release
+        # We pin to the SHA, not the tag, for security reasons.
+        # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+        uses: softprops/action-gh-release@de2c0eb89ae2a093876385947365aca7b0e5f844 # v0.1.15
+        with:
+          prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
+          files: |
+            ${{ env.DOCS }}
+            ${{ env.DIST }}
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    # TODO: Use the CI straight from the template
+    uses: ./.github/workflows/_check.yml
+
+  docs:
+    needs: check
+    if: ${{ ! needs.check.outputs.branch-pr }}
+    uses: ./.github/workflows/_docs.yml
+
+  pages:
+    if: github.ref_name == 'main'
+    needs: docs
+    uses: ./.github/workflows/_pages.yml
+    permissions:
+      pages: write
+      id-token: write
+
+  release:
+    if: github.ref_type == 'tag'
+    needs: [dist, docs]
+    # TODO: Use the CI straight from the template
+    uses: ./.github/workflows/_release.yml
+    permissions:
+      contents: write
diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml
@@ -0,0 +1,26 @@
+name: Link Check
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run weekly to check URL links still resolve
+    - cron: "0 8 * * WED"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install python packages
+        uses: pip install -c requirements.txt
+
+      - name: Check links
+        run: sphinx-build -b linkcheck -T docs build/html
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+build/