Docs sourced GitHub actions

.github/workflows/docs.yml

@@ -4,22 +4,46 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+      - name: Checkout
+        uses: actions/checkout@v4
 
-      - uses: astral-sh/setup-uv@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
 
-      - name: Install docs dependencies
+      - name: Install documentation dependencies
         run: uv sync --extra docs
 
-      - name: Deploy to GitHub Pages
-        run: uv run mkdocs gh-deploy --force
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Upload documentation
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+      - name: Deploy documentation
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -75,6 +75,14 @@ Add tests for new implementations and run the suite:
 uv run pytest tests
 ```
 
+### Documentation
+
+Any documentation changes would be deployed automatically after a PR merges main. However, please verify locally first with
+
+```bash
+uv run --extra docs mkdocs serve
+```
+
 ## Citation
 
 If you use this package, please cite:

docs/api/core.md

@@ -0,0 +1,3 @@
+# Core API
+
+::: PtyLab

docs/api/engines.md

@@ -0,0 +1,5 @@
+# Engines
+
+::: PtyLab.Engines
+    options:
+      show_submodules: true

docs/api/experimental-data.md

@@ -0,0 +1,5 @@
+# Experimental Data
+
+::: PtyLab.ExperimentalData
+    options:
+      show_submodules: true

docs/api/grid-generation.md

@@ -0,0 +1,5 @@
+# Grid Generation
+
+::: PtyLab.GridGeneration
+    options:
+      show_submodules: true

docs/api/index.md

@@ -0,0 +1,4 @@
+# API Reference
+
+The API reference is generated from PtyLab's Python docstrings. It covers the
+public modules and members in each package.

docs/api/io.md

@@ -0,0 +1,5 @@
+# Input and Output
+
+::: PtyLab.io
+    options:
+      show_submodules: true

docs/api/monitoring.md

@@ -0,0 +1,5 @@
+# Monitoring
+
+::: PtyLab.Monitor
+    options:
+      show_submodules: true

docs/api/operators.md

@@ -0,0 +1,5 @@
+# Operators
+
+::: PtyLab.Operators
+    options:
+      show_submodules: true

docs/api/parameters.md

@@ -0,0 +1,5 @@
+# Parameters
+
+::: PtyLab.Params
+    options:
+      show_submodules: true

docs/api/probe-engines.md

@@ -0,0 +1,5 @@
+# Probe Engines
+
+::: PtyLab.ProbeEngines
+    options:
+      show_submodules: true

docs/api/reconstruction.md

@@ -0,0 +1,5 @@
+# Reconstruction
+
+::: PtyLab.Reconstruction
+    options:
+      show_submodules: true

docs/api/regularizers.md

@@ -0,0 +1,5 @@
+# Regularizers
+
+::: PtyLab.Regularizers
+    options:
+      show_submodules: true

docs/api/utilities.md

@@ -0,0 +1,5 @@
+# Utilities
+
+::: PtyLab.utils
+    options:
+      show_submodules: true

mkdocs.yml

@@ -23,6 +23,8 @@ theme:
         icon: material/brightness-4
         name: Switch to light mode
   features:
+    - navigation.tabs
+    - navigation.tabs.sticky
     - navigation.sections
     - navigation.expand
     - navigation.indexes
@@ -60,6 +62,20 @@ nav:
     - "05 – CPM Reflection": tutorials/tutorial_reflectionPtychography.ipynb
     - "06 – CPM Interferometric Intensity": tutorials/tutorial_interferometricIntensityConstraint.ipynb
     - "07 – FPM": tutorials/tutorial_FPM.ipynb
+  - API Reference:
+    - api/index.md
+    - Core: api/core.md
+    - Engines: api/engines.md
+    - Experimental Data: api/experimental-data.md
+    - Grid Generation: api/grid-generation.md
+    - Monitoring: api/monitoring.md
+    - Operators: api/operators.md
+    - Parameters: api/parameters.md
+    - Probe Engines: api/probe-engines.md
+    - Reconstruction: api/reconstruction.md
+    - Regularizers: api/regularizers.md
+    - Input and Output: api/io.md
+    - Utilities: api/utilities.md
 
 extra_css:
   - stylesheets/extra.css
@@ -79,6 +95,15 @@ markdown_extensions:
 
 plugins:
   - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths:
+            - .
+          options:
+            show_root_heading: true
+            show_source: true
+            members_order: source
   - mkdocs-jupyter:
       include: ["*.ipynb"]
       execute: false

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ptylab"
-version = "0.3.1"
+version = "0.3.2"
 description = "A cross-platform, open-source inverse modeling toolbox for conventional and Fourier ptychography"
 authors = [
     { name = "Lars Loetgering", email = "lars.loetgering@fulbrightmail.org" },
@@ -37,6 +37,7 @@ docs = [
     "mkdocs>=1.6.1",
     "mkdocs-material>=9.7.6",
     "mkdocs-jupyter>=0.24",
+    "mkdocstrings[python]>=1.0.6",
 ]
 
 [project.scripts]