Fix missing .bindings submodule in API doc website

.github/workflows/docs.yaml

@@ -1,38 +1,61 @@
 ---
-name: Publish API documentation to GitHub Pages
+# Publish library landing page to
+# https://spdx.github.io/spdx-python-model/
+#
+# Publish API docs to
+# https://spdx.github.io/spdx-python-model/doc/stable/ -- latest release
+# https://spdx.github.io/spdx-python-model/doc/dev/ -- from main branch (unreleased)
+# https://spdx.github.io/spdx-python-model/doc/1.0/ -- for specific version (all 1.0.x will all published to this URL)
+
+name: Publish API docs
 
 on:
   push:
     branches:
       - main
+    paths:
+      - '.github/workflows/docs.yaml'
+      - 'gen/**'
+      - 'src/**'
+      - 'www/**'
+      - 'README.md'
+      - 'pyproject.toml'
   release:
     types: [published]
   workflow_dispatch:
 
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 jobs:
   deploy-docs:
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
 
+      - name: Keep previously published versions
+        run: |
+          mkdir -p pages
+          if git fetch origin gh-pages 2>/dev/null; then
+            git archive origin/gh-pages | tar -x -C pages/
+          fi
+
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.14"
 
       - name: Install dependencies
-        run: pip install .
+        run: pip install -e .
+        # Use editable install (-e) to include the generated binding submodules
+        # into the source tree so pdoc can see them.
 
       - name: Install pdoc
         run: pip install pdoc
@@ -42,32 +65,54 @@ jobs:
         run: |
           if [[ "${{ github.event_name }}" == "release" ]]; then
             VERSION_RAW="${{ github.event.release.tag_name }}"
-            echo "VERSION=${VERSION_RAW#v}" >> $GITHUB_ENV
+            VERSION="${VERSION_RAW#v}"
+            echo "VERSION=$VERSION" >> $GITHUB_ENV
+            echo "MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1-2)" >> $GITHUB_ENV
+            echo "IS_RELEASE=true" >> $GITHUB_ENV
           else
             echo "VERSION=dev" >> $GITHUB_ENV
+            echo "MAJOR_MINOR=dev" >> $GITHUB_ENV
+            echo "IS_RELEASE=false" >> $GITHUB_ENV
           fi
 
       - name: Build docs
-        env:
-          VERSION: ${{ env.VERSION }}
         run: |
-          pdoc src/spdx_python_model -o docs
-          # Copy files to versioned/dev directory
-          mkdir -p "pages/${{ env.VERSION }}"
-          cp -r docs/* "pages/${{ env.VERSION }}/"
-          # Create an index.html to redirect to the dev docs
-          if [[ "${{ env.VERSION }}" == "dev" ]]; then
-            echo '<meta http-equiv="refresh" content="0; url=dev/" />' > pages/index.html
+          OUT="pages/doc/$MAJOR_MINOR"
+
+          mkdir -p "$OUT"
+
+          # Build API docs into the versioned output directory.
+          pdoc spdx_python_model \
+            --logo "https://raw.githubusercontent.com/spdx/outreach/main/assets/SPDX_Logo/svg/SPDX%20logo%20color.svg" \
+            --logo-link "/spdx-python-model/doc/$MAJOR_MINOR/" \
+            --footer-text "spdx-python-model $VERSION" \
+            -o "$OUT"
+
+          # On release: update stable/ to match this major.minor.
+          if [[ "$IS_RELEASE" == "true" ]]; then
+            rm -rf pages/doc/stable
+            cp -r "pages/doc/$MAJOR_MINOR" pages/doc/stable
+          fi
+
+          # /doc/ redirects to site root.
+          mkdir -p pages/doc
+          echo '<meta http-equiv="refresh" content="0; url=../" />' > pages/doc/index.html
+
+          # Root landing page from repo; fallback to redirect if not present.
+          if [[ -f www/index.html ]]; then
+            cp www/index.html pages/index.html
+          else
+            echo '<meta http-equiv="refresh" content="0; url=doc/stable/" />' > pages/index.html
           fi
 
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: pages
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

src/spdx_python_model/__init__.py

@@ -1,11 +1,7 @@
 # SPDX-FileType: SOURCE
 # SPDX-License-Identifier: Apache-2.0
-#
 """
-SPDX 3 model.
-
-.. include:: ../../README.md
-   :end-before: Testing
+Python bindings for the SPDX 3 data model.
 """
 
 import importlib
@@ -20,10 +16,17 @@
 
 if TYPE_CHECKING:
     # Generated re-exports to give type checkers version types.
-    # No imported during runtime.
+    # Not imported during runtime.
     from .bindings._reexport import *  # noqa: F403
 
-__all__ = ["LoadError", "VERSION", "__version__", "load", "load_data"]
+__all__ = [
+    "bindings",  # generated # noqa: F405
+    "LoadError",
+    "VERSION",
+    "__version__",
+    "load",
+    "load_data",
+]
 
 # Version submodule names accepted by __getattr__ for top-level import.
 _VERSION_MODULES = frozenset(_CONTEXT_TABLE.values())

www/index.html

@@ -0,0 +1,78 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>SPDX Python Model</title>
+  <meta name="description"
+    content="Python bindings for the SPDX 3 data model. Install instructions. API documentation.">
+  <style>
+    body {
+      font-family: system-ui, sans-serif;
+      max-width: 640px;
+      margin: 4rem auto;
+      padding: 0 1.5rem;
+      color: #222;
+    }
+
+    h1 {
+      margin-bottom: 0.25rem;
+    }
+
+    p.tagline {
+      color: #555;
+      margin-top: 0;
+    }
+
+    pre {
+      background: #f4f4f4;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      padding: 0.75rem 1rem;
+      font-size: 1rem;
+    }
+
+    a {
+      color: #0969da;
+    }
+
+    li {
+      margin-bottom: 0.5rem;
+    }
+  </style>
+</head>
+
+<body>
+  <h1>SPDX Python Model</h1>
+  <p class="tagline">Python bindings for the SPDX 3 data model.</p>
+
+  <h2>Install</h2>
+  <p>Install the latest version from <a href="https://pypi.org/project/spdx-python-model/">PyPI</a>:</p>
+  <pre>pip install spdx-python-model</pre>
+
+  <h2>API documentation</h2>
+  <ul>
+    <li><a href="doc/stable/">Stable API docs</a></li>
+    <li><a href="doc/dev/">Development API docs</a> (unreleased)</li>
+  </ul>
+  <p>Documentation for each version of the SPDX 3 model is in the
+    <code>spdx_python_model.bindings.<em>VERSION</em>.model</code> submodule.
+  </p>
+
+  <h2>Source code</h2>
+  <p>Source code and README are available on GitHub:
+    <a href="https://github.com/spdx/spdx-python-model/">https://github.com/spdx/spdx-python-model/</a>.
+  </p>
+
+  <h2>License</h2>
+  <p>SPDX Python Model is licensed under the <a href="https://spdx.org/licenses/Apache-2.0.html">Apache License 2.0</a>
+    (<code>Apache-2.0</code>).</p>
+
+  <h2>More SPDX tools</h2>
+  <p>See <a href="https://spdx.dev/use/spdx-tools/">SPDX Tools</a> on the official SPDX project website for more tools
+    supporting SPDX.</p>
+
+</body>
+
+</html>