Add hybrid mkpages and Sphinx docs build for Pages

.github/workflows/publish-docs.yml

@@ -3,8 +3,7 @@ name: publish-docs
 on:
   push:
     branches:
-      - master
-      - main
+      - "**"
   workflow_dispatch:
 
 permissions:
@@ -13,7 +12,7 @@ permissions:
   id-token: write
 
 concurrency:
-  group: pages
+  group: pages-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -32,34 +31,75 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Install package
+      - name: Install package and docs tooling
         run: |
           python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -e ".[dev]"
+          python -m pip install mkpages
+          python -m pip install -e ".[dev,docs]"
 
       - name: Generate benchmark report
         run: |
           python scripts/benchmark.py --json benchmark.json > benchmark.md
 
-      - name: Build Jekyll source tree
+      - name: Stage mkpages content tree
         run: |
-          python scripts/build_pages_site.py \
-            --output _site_src \
+          python scripts/stage_mkpages_site.py \
+            --output .mkpages-src \
             --benchmark-summary benchmark.md \
             --benchmark-json benchmark.json
 
+      - name: Build mkpages source tree
+        run: |
+          mkpages build .mkpages-src --output .mkpages
+
+      - name: Build Sphinx API docs
+        run: |
+          sphinx-build -M dirhtml sphinx .sphinx
+
+      - name: Merge Sphinx output into mkpages tree
+        run: |
+          cp -R .sphinx/dirhtml/api .mkpages/api
+          cp -R .sphinx/dirhtml/_static .mkpages/_static
+          cp -R .sphinx/dirhtml/genindex .mkpages/genindex
+          cp -R .sphinx/dirhtml/py-modindex .mkpages/py-modindex
+          cp -R .sphinx/dirhtml/search .mkpages/search
+          cp .sphinx/dirhtml/objects.inv .mkpages/objects.inv
+          cp .sphinx/dirhtml/searchindex.js .mkpages/searchindex.js
+
+      - name: Allow Sphinx static assets through Jekyll
+        run: |
+          printf '\ninclude:\n  - _static\n' >> .mkpages/_config.yml
+
       - name: Build site with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:
-          source: _site_src
+          source: .mkpages
           destination: _site
 
+      - name: Verify published inventory
+        run: test -f _site/objects.inv
+
+      - name: Prepare artifact name
+        id: artifact_name
+        shell: bash
+        run: |
+          safe_ref=$(printf '%s' "${GITHUB_REF_NAME}" | tr '/\\:*?\"<>|\r\n' '-')
+          echo "value=docs-site-${safe_ref}" >> "$GITHUB_OUTPUT"
+
+      - name: Upload downloadable site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.artifact_name.outputs.value }}
+          path: _site
+
       - name: Upload Pages artifact
+        if: github.ref_name == 'main' || github.ref_name == 'master'
         uses: actions/upload-pages-artifact@v3
         with:
           path: _site
 
   deploy:
+    if: github.ref_name == 'main' || github.ref_name == 'master'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.gitignore

@@ -14,4 +14,5 @@ pyseq.egg-info/
 default.env
 .codex
 .agents/
-.pytest_cache/
+.pytest_cache/
+.mkpages/

docs/README.md

@@ -14,4 +14,5 @@ Available guides:
 
 If you are evaluating pyseq for pipeline use, start with the examples guide and
 then review the CLI reference for the sequence-aware utilities included with
-the package.
+the package. For generated Python API details, see the [Sphinx API
+reference](/api/).

docs/examples.md

@@ -3,6 +3,8 @@
 This guide expands on the examples in the main [README](../README.md) and
 shows a few common ways pyseq is used in production scripts and tools.
 
+For the generated Python API reference, see [Sphinx API reference](/api/).
+
 ## Parse a List of Frames into a Sequence
 
 ```python

docs/index.md

@@ -1,5 +1,5 @@
 <p align="left">
-  <img src="assets/logo.png" alt="pyseq logo" width="640">
+  <img src="assets/logo.png" alt="pyseq logo" width="400">
 </p>
 
 pyseq is a **Python library for detecting, parsing, and formatting numbered
@@ -127,7 +127,8 @@ Expected output:
 
 ## Learn More
 
-- [PySeq Docs](README.md): docs overview
+- [API Reference](/api/): generated Python module reference
+- [PySeq Docs](/docs/): docs overview
 - [Examples](examples.md): Python and CLI usage patterns
 - [CLI Tools Reference](cli-tools.md): bundled sequence-aware utilities
 - [Formatting Reference](formatting.md): supported format directives

docs/mkpages.yml

@@ -0,0 +1,17 @@
+title: pyseq
+description: Python library for numbered file sequences.
+navigation:
+  - label: Home
+    href: /
+  - label: Usage
+    href: /docs/cli-tools/
+  - label: Examples
+    href: /docs/examples/
+  - label: Formatting
+    href: /docs/formatting/
+  - label: Performance
+    href: /docs/performance/
+  - label: API
+    href: /api/
+  - label: GitHub
+    href: https://github.com/rsgalloway/pyseq

lib/pyseq/seq.py

@@ -101,10 +101,10 @@ def padsize(item, frame):
     For example: the file item.001.exr will have a pad size of 3, and the
     file test.001001.exr will have a pad size of 6.
 
-    :param item: Item object.
     Signed frames use the digit width only; the leading ``-`` does not
     contribute to the padding width.
 
+    :param item: Item object.
     :param frame: The frame number token as a string.
     :returns: The size of the frame pad as an int.
     """
@@ -777,6 +777,7 @@ def append(self, item: Item, check_membership: bool = True):
         :param item: pyseq.Item object.
         :param check_membership: Check if `item` is a member. Can be useful if
             membership is checked prior to appending.
+
         :exc:`SequenceError` raised if item is not a sequence member.
         """
 

pyproject.toml

@@ -40,7 +40,21 @@ classifiers = [
 authors = [
   { name = "Ryan Galloway", email = "ryan@rsgalloway.com" },
 ]
-optional-dependencies = { dev = ["pytest", "flake8==7.1.1", "mccabe==0.7.0", "isort==5.13.2", "black==24.8.0"], test = ["pytest"] }
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "flake8==7.1.1",
+  "mccabe==0.7.0",
+  "isort==5.13.2",
+  "black==24.8.0",
+]
+docs = [
+  "Sphinx>=8,<9",
+]
+test = [
+  "pytest",
+]
 
 [tool.isort]
 profile = "black"