autodeploy docs to github pages

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+# 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:
+  push:
+    branches:
+      - main
+      - dev
+  release:
+    types:
+      - published
+  pull_request:
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      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: Install package
+      #   run: python -m pip install .
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: sphinx-notes/pages@v3

docs/conf.py

@@ -6,19 +6,25 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-import os
+from pathlib import Path
 import time
 import sys
 
 from importlib.metadata import metadata
 
+# Need to make sure that krank can be imported, and also that
+# it is importing the local one (as opposed to a previously pip installed one).
+# 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, os.path.abspath("../krank/src"))
-
+sys.path.insert(0, str(Path(__file__).parents[1].joinpath("src")))
 import krank
 
+
 project = krank.__name__
 release = krank.__version__  # Full project version
 version = krank.__version__[:3]  # Major project version
@@ -106,14 +112,23 @@
         {"name": "Contributing", "url": "https://github.com/remrama/krank#contributing"},
     ],
     "header_links_before_dropdown": 4,
+    "navbar_start": ["navbar-logo", "navbar-icon-links"],  # "version-switcher"
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": [],
+    # "navbar_persistent": [],  # Default is a nice search bubble that I otherwise don't get
+    "search_bar_text": "Search...",
+    # "article_header_start": ["breadcrumbs"],
+    # "article_header_end": [],
+    # "article_footer_items": [],
+    "footer_start": ["last-updated"],  # "search-field" "search-button"
+    "footer_center": [],
+    "footer_end": [],  # "theme-switcher"
+    "content_footer_items": [],
+    "show_prev_next": False,
     # "sidebarwidth": 230,
     # "navbar_start": ["navbar-logo", "version-switcher"],
     "show_version_warning_banner": True,
     "announcement": "BEWARE! This project is in the <a href='https://github.com/remrama/krank'>planning stage</a>.",
-    # "navbar_end": ["theme-switcher", "navbar-icon-links"],
-    "navbar_end": ["navbar-icon-links"],
-    # "navbar_end": ["theme-switcher", "navbar-icon-links", "search-field"],
-    # "search_bar_text": "Search for something...",
     "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     "show_nav_level": 3,
     "show_toc_level": 3,
@@ -126,7 +141,7 @@
     # "icon_links_label": "Quick Links",
     "icon_links": [
         {
-            "name": "GitHub",
+            "name": "Krank on GitHub",
             "url": "https://github.com/remrama/krank",
             "icon": "fa-brands fa-square-github",
             "type": "fontawesome",

docs/index.rst

@@ -2,6 +2,7 @@
 .. image:: https://badge.fury.io/py/krank.svg
    :target: https://badge.fury.io/py/krank
 
+----
 
 Krank
 =====

docs/requirements.txt

@@ -0,0 +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]