another test

.github/workflows/docs.yml

@@ -1,10 +1,21 @@
-# Simple workflow for deploying static content to GitHub Pages
-name: Deploy static content to Pages
+# Workflow for building sphinx documentation remotely
+# and deploying the static HTML to a GitHub Pages site.
+# Note this approach does not require the static HTML
+# files to be stored/pushed/committed to an alternate
+# pages branch or anything like that. It uses GitHub
+# Action artifacts...
+name: Build and Deploy Sphinx Docs to GitHub Pages
 
 on:
-  # Runs on pushes targeting the default branch
   push:
-    branches: ["docs"]
+    branches:
+      - main
+      - dev
+      - docs
+  release:
+    types:
+      - published
+  pull_request:
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -27,15 +38,14 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
+      ## These help to install krank remotely
+      ## So it's importable in conf.py, but I
+      ## think this is solved with a relative
+      ## import now in conf.py.
       # - name: Checkout
       #   uses: actions/checkout@v4
-      # - name: Setup Pages
-      # - name: Upload artifact
-      #   uses: actions/upload-pages-artifact@v3
-      #   with:
-      #     path: "./docs"  # Upload entire repository
       # - name: Install package
       #   run: python -m pip install .
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: sphinx-notes/pages@v3
+        uses: sphinx-notes/pages@v3

docs/conf.py

@@ -17,6 +17,8 @@
 # So this can be from the krank/src/krank directory or through a locally
 # built or locally pip installed version.
 #
+# This prevents the need to build krank manually in the github action for pages.
+#
 # autodoc needs to import your modules in order to extract the docstrings.
 # Therefore, you must add the appropriate path to sys.path in your conf.py.
 sys.path.insert(0, str(Path(__file__).parents[1].joinpath("src")))

docs/requirements.txt

@@ -1 +1,10 @@
+# This is redundant with dev dependencies in pyproject.toml.
+# It is used by the sphinx-notes/pages@v3 GitHub Action used
+# to build the documentation remotely. It installs sphinx
+# automatically, but need to add additional requirements
+# that are installed during documentation building.
+#
+# There's a way to customize that GitHub action so maybe this
+# could be avoided, but okay.
+
 pydata-sphinx-theme

pyproject.toml

@@ -41,7 +41,7 @@ Homepage = "https://github.com/remrama/krank"
 [project.optional-dependencies]
 dev = [
   "sphinx",
-  "pydata-sphinx-theme",
+  "pydata-sphinx-theme",  # Needs to be in requirements.txt also (for docs.yml).
 ]
 
 [tool.setuptools]