add documentation framework

Author: gilesknap

.copier-answers.yml

@@ -3,11 +3,11 @@ _commit: 5.0.1
 _src_path: https://github.com/diamondlightsource/python-copier-template
 author_email: giles.knap@diamond.ac.uk
 author_name: Giles Knap
-description: a container that mounts remote devices locally using anywhereusb
+description: A client-server application for remotely sharing USB devices with usbip
 distribution_name: usb-remote
 docker: true
 docker_debug: false
-docs_type: README
+docs_type: sphinx
 git_platform: github.com
 github_org: epics-containers
 package_name: usb_remote

.github/workflows/_docs.yml

@@ -0,0 +1,55 @@
+on:
+  workflow_call:
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Avoid git conflicts when tag and branch pushed at same time
+        if: github.ref_type == 'tag'
+        run: sleep 60
+
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          # Need this to get version number from last tag
+          fetch-depth: 0
+
+      - name: Install system packages
+        run: sudo apt-get install graphviz
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build docs
+        run: uv run --locked tox -e docs
+
+      - name: Remove environment.pickle
+        run: rm build/html/.doctrees/environment.pickle
+
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: build
+
+      - name: Sanitize ref name for docs version
+        run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV
+
+      - name: Move to versioned directory
+        run: mv build/html .github/pages/$DOCS_VERSION
+
+      - name: Write switcher.json
+        run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
+
+      - name: Publish Docs to gh-pages
+        if: github.ref_type == 'tag' || github.ref_name == 'main'
+        # 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@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .github/pages
+          keep_files: true

.github/workflows/ci.yml

@@ -36,6 +36,11 @@ jobs:
       contents: read
       packages: write
 
+  docs:
+    uses: ./.github/workflows/_docs.yml
+    permissions:
+      contents: write
+
   dist:
     uses: ./.github/workflows/_dist.yml
 
@@ -47,7 +52,7 @@ jobs:
       id-token: write
 
   release:
-    needs: [dist, test]
+    needs: [dist, test, docs]
     if: github.ref_type == 'tag'
     uses: ./.github/workflows/_release.yml
     permissions:

.github/workflows/periodic.yml

@@ -0,0 +1,13 @@
+name: Periodic
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run weekly to check URL links still resolve
+    - cron: "0 8 * * WED"
+
+jobs:
+  linkcheck:
+    uses: ./.github/workflows/_tox.yml
+    with:
+      tox: docs -- -b linkcheck

README.md

@@ -11,14 +11,9 @@ Source          | <https://github.com/epics-containers/usb-remote>
 :---:           | :---:
 PyPI            | `pip install usb-remote`
 Docker          | `docker run ghcr.io/epics-containers/usb-remote:latest`
+Documentation   | <https://epics-containers.github.io/usb-remote>
 Releases        | <https://github.com/epics-containers/usb-remote/releases>
 
-## Documentation
-
-- **[Quick Start Guide](docs/QUICKSTART.md)** - Get started from installation to first device share
-- **[Architecture](docs/ARCHITECTURE.md)** - Understand the client-server model and design
-- **[Raspberry Pi Setup](docs/RASBERRYPI.md)** - Guide to setting up a Raspberry Pi as a USB server
-
 ## Multi-Server Configuration
 
 You can configure `usb-remote` to scan multiple USB device servers automatically. The client discovers configuration files in the following priority order:
@@ -150,3 +145,7 @@ usb-remote uninstall-service
 # Uninstall system service (requires sudo)
 sudo usb-remote uninstall-service --system
 ```
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+See https://epics-containers.github.io/usb-remote for more detailed documentation.