Generate and publish API docs to GitHub pages

I suspect we'll need a more actively maintained docs tool that supports
versions etc in future. Unfortunately Sphinx and Pydoc both seem more
heavyweight than I'd like right now, and I can't find any other great
options.

Signed-off-by: Nic Cope <[email protected]>

.github/workflows/ci.yml

@@ -12,6 +12,19 @@ on:
         description: PyPI project version (e.g. v0.1.0)
         required: false
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued. However, do NOT cancel in-progress runs as we
+# want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 env:
   # Common versions
   PYTHON_VERSION: '3.11.5'
@@ -113,3 +126,36 @@ jobs:
           # be enabled, which makes sharing the account hard. We're waiting for
           # a crossplane org to be approved.
           password: ${{ secrets.PYPI_API_TOKEN }}
+
+
+  docs:
+    # The simple docs tool we're using doesn't support versions, so our docs
+    # will only reflect what's in main.
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Setup Hatch
+        run: pipx install hatch==1.7.0
+
+      - name: Build Documentation
+        run: hatch run docs:pdoc -d google crossplane/function -o docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -158,3 +158,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# We don't commit our docs - instead we generate them and upload to GitHub pages.
+docs

pyproject.toml

@@ -16,11 +16,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
 ]
 
-dependencies = [
-  "grpcio==1.*",
-  "grpcio-reflection==1.*",
-  "structlog==23.*",
-]
+dependencies = ["grpcio==1.*", "grpcio-reflection==1.*", "structlog==23.*"]
 
 dynamic = ["version"]
 
@@ -31,7 +27,7 @@ Source = "https://github.com/crossplane/function-sdk-python"
 
 [tool.hatch.version]
 path = "crossplane/function/__version__.py"
-validate-bump = false # Allow going from 0.0.0.dev0+x to 0.0.0.dev0+y.
+validate-bump = false                       # Allow going from 0.0.0.dev0+x to 0.0.0.dev0+y.
 
 [tool.hatch.envs.default]
 type = "virtual"
@@ -63,6 +59,14 @@ path = ".venv-test"
 [tool.hatch.envs.test.scripts]
 unit = "python -m unittest tests/*.py"
 
+[tool.hatch.envs.docs]
+type = "virtual"
+path = ".venv-docs"
+dependencies = ["pdoc"]
+
+[tool.hatch.envs.docs.scripts]
+generate = "pdoc -m google crossplane/function -o docs"
+
 [tool.hatch.build.targets.wheel]
 packages = ["crossplane"]