docs: Add initial sphinx documentation

The documentation is still a work in progress.

.firebaserc

@@ -7,9 +7,12 @@
       "hosting": {
         "app": [
           "neuroglancer"
+        ],
+        "docs": [
+          "neuroglancer-docs"
         ]
       }
     }
   },
   "etags": {}
-}
+}

.github/workflows/build.yml

@@ -97,7 +97,7 @@ jobs:
       # - name: Setup tmate session
       #   uses: mxschmitt/action-tmate@v3
       - name: Install Python packaging/test tools
-        run: python -m pip install --upgrade pip tox nox wheel numpy -r python/requirements-test.txt
+        run: pip install --upgrade pip tox nox wheel numpy -r python/requirements-test.txt
       - uses: ./.github/actions/setup-firefox
       - run: nox -s lint format mypy
       - name: Check for dirty working directory
@@ -174,13 +174,37 @@ jobs:
             dist/*.whl
             dist/*.tar.gz
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2
+        with:
+          macos-skip-brew-update: "true"
+      - name: Install nox
+        run: pip install nox
+      - name: Build docs
+        run: nox -s docs
+      - name: Upload docs as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: |
+            dist/docs
+
   publish-package:
     # Only publish package on push to tag or default branch.
     if: ${{ github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/master') }}
     runs-on: ubuntu-latest
     needs:
       - "client"
       - "python-build-package"
+      - "docs"
     steps:
       - uses: actions/checkout@v4
       - name: Use Node.js
@@ -220,12 +244,26 @@ jobs:
         with:
           name: client
           path: dist/client
-      - name: Publish to Firebase hosting
+      - name: Publish client to Firebase hosting
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          firebaseServiceAccount: "${{ secrets.FIREBASE_HOSTING_SERVICE_ACCOUNT_KEY }}"
+          projectId: neuroglancer-demo
+          channelId: live
+          target: app
+      # Download dist/docs after publishing to PyPI, because PyPI publish
+      # action fails if dist/docs directory is present.
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: dist/docs
+      - name: Publish docs to Firebase hosting
         uses: FirebaseExtended/action-hosting-deploy@v0
         with:
           firebaseServiceAccount: "${{ secrets.FIREBASE_HOSTING_SERVICE_ACCOUNT_KEY }}"
           projectId: neuroglancer-demo
           channelId: live
+          target: docs
 
   ngauth:
     strategy:

.github/workflows/build_docs_preview.yml

@@ -0,0 +1,29 @@
+name: Build docs preview
+
+on:
+  pull_request:
+
+jobs:
+  upload:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2
+        with:
+          macos-skip-brew-update: "true"
+      - name: Install nox
+        run: pip install nox
+      - name: Build documentation
+        run: nox -s docs
+      - name: Upload client as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: |
+            dist/docs/

.github/workflows/deploy_docs_preview.yml

@@ -0,0 +1,67 @@
+name: Deploy docs preview
+
+on:
+  workflow_run:
+    workflows: ["Build docs preview"]
+    types: [completed]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: "Create commit status"
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const commitId = "${{ github.event.workflow_run.head_commit.id }}";
+            await github.rest.repos.createCommitStatus({
+                context: "docs-preview",
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                sha: commitId,
+                state: "pending",
+                description: `Creating preview`,
+                target_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            });
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: dist/docs
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+          run-id: "${{ github.event.workflow_run.id }}"
+      - name: Get PR ID
+        # https://github.com/orgs/community/discussions/25220#discussioncomment-7532132
+        id: pr-id
+        run: |
+          PR_ID=$(gh run view -R ${{ github.repository }} ${{ github.event.workflow_run.id }} | grep -oP '#[0-9]+ . ${{ github.event.workflow_run.id }}' | grep -oP '#[0-9]+' | cut -c 2-)
+          echo "pr-id=${PR_ID}" >> $GITHUB_OUTPUT
+        env:
+          GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+      - uses: FirebaseExtended/action-hosting-deploy@v0
+        id: deploy
+        with:
+          repoToken: "${{ secrets.GITHUB_TOKEN }}"
+          firebaseServiceAccount: "${{ secrets.FIREBASE_HOSTING_SERVICE_ACCOUNT_KEY }}"
+          expires: 30d
+          channelId: "pr${{ steps.pr-id.outputs.pr-id }}-docs"
+          projectId: neuroglancer-demo
+          target: docs
+      - name: "Update commit status"
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const expires = new Date("${{ steps.deploy.outputs.expire_time }}");
+            const commitId = "${{ github.event.workflow_run.head_commit.id }}";
+            await github.rest.repos.createCommitStatus({
+                context: "docs-preview",
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                sha: commitId,
+                state: "success",
+                target_url: "${{ steps.deploy.outputs.details_url }}",
+                description: `Preview created, expires at: ${expires.toISOString()}`,
+            });

.github/workflows/deploy_preview.yml

@@ -48,6 +48,7 @@ jobs:
           expires: 30d
           channelId: "pr${{ steps.pr-id.outputs.pr-id }}"
           projectId: neuroglancer-demo
+          target: docs
       - name: "Update commit status"
         uses: actions/github-script@v7
         with: