Transition from RTD to GitHub Pages docs deployment

.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - dev
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y graphviz
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install the project
+        run: uv sync --only-group docs
+
+      - name: Build documentation
+        run: |
+          cd docs
+          uv run make html
+
+      - name: Add .nojekyll file
+        run: touch docs/build/html/.nojekyll
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/build/html'
+
+  deploy:
+    # Only deploy on push to main or release tags
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
 docs/source/_build
 docs/source/generated
 

docs/source/conf.py

@@ -1,13 +1,26 @@
 # Configuration file for the Sphinx documentation builder.
 
+import os
+import sys
+
 # -- Project information --------------------------
 
 project = "ezmsg"
 copyright = "2022, JHU/APL"
 author = "JHU/APL"
 
-release = "3.3.4"
-version = "3.3.4"
+# Read version from pyproject.toml
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+pyproject_path = os.path.join(os.path.dirname(__file__), "../../pyproject.toml")
+with open(pyproject_path, "rb") as f:
+    pyproject_data = tomllib.load(f)
+    release = pyproject_data["project"]["version"]
+    version = release
+
 
 # -- General configuration --------------------------
 
@@ -16,22 +29,20 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.duration",
-    "sphinx.ext.graphviz",
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
     "sphinx.ext.napoleon",
-    "sphinxext.rediraffe",
-    "myst_parser",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
-    "sphinx_design",
 ]
 
 templates_path = ["_templates"]
 
-source_suffix = [".rst", ".md"]
+source_suffix = [".rst"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+add_module_names = True
+
 # The toctree master document
 master_doc = "index"
 
@@ -41,17 +52,16 @@
 # -- Autodoc configuration ------------------------------
 autodoc_typehints_format = "short"
 python_use_unqualified_type_names = True
-autodoc_type_aliases = {
-    "numpy.typing.NDArray": "numpy NDArray",
-}
 
 # -- Intersphinx configuration --------------------------
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3/", None),
-    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
-    "numpy": ("https://numpy.org/doc/stable/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "ezmsg.sigproc": ("https://www.ezmsg.org/ezmsg-sigproc", None),
+    "ezmsg.lsl": ("https://www.ezmsg.org/ezmsg-lsl", None),
+    "ezmsg.learn": ("https://www.ezmsg.org/ezmsg-learn", None),
 }
 intersphinx_disabled_domains = ["std"]
 
@@ -60,26 +70,18 @@
 html_theme = "pydata_sphinx_theme"
 html_logo = "_static/_images/ezmsg_logo.png"
 html_favicon = "_static/_images/ezmsg_logo.png"
+html_title = f"ezmsg {version}"
 
 html_static_path = ["_static"]
 
-# Redirects for pages that are unavailable or moved
-rediraffe_redirects = {
-    "about.rst": "explanations/content-explanations.rst",
-    "getting-started.rst": "tutorials/start.rst",
-}
-
 # Timestamp is inserted at every page bottom in this strftime format.
 html_last_updated_fmt = '%Y-%m-%d'
 
 # -- Options for EPUB output --------------------------
 epub_show_urls = "footnote"
 
-add_module_names = False
-
 branch = "main"
-code_url = f"https://github.com/iscoe/ezmsg/blob/{branch}/"
-sigproc_code_url = f"https://github.com/ezmsg-org/ezmsg-sigproc/blob/{branch}/"
+code_url = f"https://github.com/ezmsg-org/ezmsg/blob/{branch}/"
 
 
 def linkcode_resolve(domain, info):
@@ -88,9 +90,7 @@ def linkcode_resolve(domain, info):
     if not info["module"]:
         return None
     filename = info["module"].replace(".", "/")
-    if "sigproc" in filename:
-        return f"{sigproc_code_url}src/{filename}.py"
-    elif "core" in filename:
+    if "core" in filename:
         return f"{code_url}src/ezmsg/core/__init__.py"
     else:
         return f"{code_url}src/{filename}.py"