From 443dc18ece726cb4bf126136cb094c12f7f791f2 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 19 Jun 2026 11:01:43 +0100 Subject: [PATCH 1/5] Build bindings submodule API docs `.bindings` submodule was previously omitted from the API docs because it was not exposed in the top-level `__all__` export. This commit fixes that. Signed-off-by: Arthit Suriyawongkul --- .github/workflows/docs.yaml | 73 ++++++++++++++++++++--------- docs/index.html | 78 +++++++++++++++++++++++++++++++ src/spdx_python_model/__init__.py | 17 ++++--- 3 files changed, 140 insertions(+), 28 deletions(-) create mode 100644 docs/index.html diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 9a8564b..5269f4a 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -1,38 +1,53 @@ --- -name: Publish API documentation to GitHub Pages +name: Publish API docs on: push: branches: - main + paths: + - '.github/workflows/docs.yaml' + - 'docs/**' + - 'gen/**' + - 'src/**' + - '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: Restore existing pages + 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 @@ -43,31 +58,47 @@ jobs: if [[ "${{ github.event_name }}" == "release" ]]; then VERSION_RAW="${{ github.event.release.tag_name }}" echo "VERSION=${VERSION_RAW#v}" >> $GITHUB_ENV + echo "IS_RELEASE=true" >> $GITHUB_ENV else echo "VERSION=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 '' > pages/index.html + VERSION="${{ env.VERSION }}" + OUT="pages/docs/$VERSION" + + mkdir -p "$OUT" + + # Build API docs directly 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/docs/$VERSION/" \ + --footer-text "spdx-python-model $VERSION" \ + -o "$OUT" + + # Update latest/ only on release events. + if [[ "${{ env.IS_RELEASE }}" == "true" ]]; then + rm -rf pages/docs/latest + cp -r "$OUT" pages/docs/latest + fi + + # Root landing page from repo; fallback to redirect if not present. + if [[ -f docs/index.html ]]; then + cp docs/index.html pages/index.html + else + echo '' > 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 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..23386be --- /dev/null +++ b/docs/index.html @@ -0,0 +1,78 @@ + + + + + + + SPDX Python Model + + + + + +

SPDX Python Model

+

Python bindings for the SPDX 3 data model.

+ +

Install

+

Install the latest version from PyPI:

+ 
pip install spdx-python-model
+ +

API documentation

+ +

Documentation for each version of the SPDX 3 model is in the + spdx_python_model.bindings.VERSION.model submodule. +

+ +

Source code

+

Source code and README are available on GitHub: + https://github.com/spdx/spdx-python-model/. +

+ +

License

+

SPDX Python Model is licensed under the Apache License 2.0 + (Apache-2.0).

+ +

More SPDX tools

+

See SPDX Tools on the official SPDX project website for more tools + supporting SPDX.

+ + + + diff --git a/src/spdx_python_model/__init__.py b/src/spdx_python_model/__init__.py index ad8a20e..ffcce34 100644 --- a/src/spdx_python_model/__init__.py +++ b/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()) From f0bd1edef6b7ab45e193444b3456ca5d7542111a Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 19 Jun 2026 11:52:31 +0100 Subject: [PATCH 2/5] Publish major.minor version Signed-off-by: Arthit Suriyawongkul --- .github/workflows/docs.yaml | 30 +++++++++++++++++++----------- {docs => www}/index.html | 4 ++-- 2 files changed, 21 insertions(+), 13 deletions(-) rename {docs => www}/index.html (93%) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 5269f4a..5aa110f 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -7,9 +7,9 @@ on: - main paths: - '.github/workflows/docs.yaml' - - 'docs/**' - 'gen/**' - 'src/**' + - 'www/**' - 'README.md' - 'pyproject.toml' release: @@ -57,38 +57,46 @@ 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 run: | VERSION="${{ env.VERSION }}" - OUT="pages/docs/$VERSION" + MAJOR_MINOR="${{ env.MAJOR_MINOR }}" + OUT="pages/doc/$MAJOR_MINOR" mkdir -p "$OUT" - # Build API docs directly into the versioned output directory. + # 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/docs/$VERSION/" \ + --logo-link "/spdx-python-model/doc/$MAJOR_MINOR/" \ --footer-text "spdx-python-model $VERSION" \ -o "$OUT" - # Update latest/ only on release events. + # On release: update stable/ to match this major.minor. if [[ "${{ env.IS_RELEASE }}" == "true" ]]; then - rm -rf pages/docs/latest - cp -r "$OUT" pages/docs/latest + rm -rf pages/doc/stable + cp -r "pages/doc/$MAJOR_MINOR" pages/doc/stable fi + # /doc/ redirects to /doc/stable/reference/. + mkdir -p pages/doc + echo '' > pages/doc/index.html + # Root landing page from repo; fallback to redirect if not present. - if [[ -f docs/index.html ]]; then - cp docs/index.html pages/index.html + if [[ -f www/index.html ]]; then + cp www/index.html pages/index.html else - echo '' > pages/index.html + echo '' > pages/index.html fi - name: Setup Pages diff --git a/docs/index.html b/www/index.html similarity index 93% rename from docs/index.html rename to www/index.html index 23386be..f98233a 100644 --- a/docs/index.html +++ b/www/index.html @@ -53,8 +53,8 @@

Install

API documentation

Documentation for each version of the SPDX 3 model is in the spdx_python_model.bindings.VERSION.model submodule. From 638e19592f8f22ac6519c6dd87568a2330e1eb1c Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 19 Jun 2026 12:02:52 +0100 Subject: [PATCH 3/5] Update docs.yaml Signed-off-by: Arthit Suriyawongkul --- .github/workflows/docs.yaml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 5aa110f..523b2fc 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -69,8 +69,6 @@ jobs: - name: Build docs run: | - VERSION="${{ env.VERSION }}" - MAJOR_MINOR="${{ env.MAJOR_MINOR }}" OUT="pages/doc/$MAJOR_MINOR" mkdir -p "$OUT" @@ -83,14 +81,14 @@ jobs: -o "$OUT" # On release: update stable/ to match this major.minor. - if [[ "${{ env.IS_RELEASE }}" == "true" ]]; then + if [[ "$IS_RELEASE" == "true" ]]; then rm -rf pages/doc/stable cp -r "pages/doc/$MAJOR_MINOR" pages/doc/stable fi - # /doc/ redirects to /doc/stable/reference/. + # /doc/ redirects to site root. mkdir -p pages/doc - echo '' > pages/doc/index.html + echo '' > pages/doc/index.html # Root landing page from repo; fallback to redirect if not present. if [[ -f www/index.html ]]; then From 8edad574b72155fd3f56841d557665bc73b4e493 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 19 Jun 2026 13:38:55 +0100 Subject: [PATCH 4/5] Add docs.yaml header description Signed-off-by: Arthit Suriyawongkul --- .github/workflows/docs.yaml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 523b2fc..e6efd10 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -1,4 +1,11 @@ --- +# 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 + name: Publish API docs on: @@ -32,7 +39,7 @@ jobs: with: fetch-depth: 0 - - name: Restore existing pages + - name: Keep previously published versions run: | mkdir -p pages if git fetch origin gh-pages 2>/dev/null; then From d1f2ce3b3d07a83f4a42446e1fdd191adcbcee95 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 19 Jun 2026 13:41:25 +0100 Subject: [PATCH 5/5] Update docs.yaml header comments Signed-off-by: Arthit Suriyawongkul --- .github/workflows/docs.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index e6efd10..e1a4fbe 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -4,7 +4,8 @@ # # 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 +# 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