From a8580365170afc463b7a26f621db227fe1f6ccc0 Mon Sep 17 00:00:00 2001 From: Niklas Melton Date: Thu, 4 Jun 2026 14:03:04 -0500 Subject: [PATCH 1/4] fix doc builds --- .github/workflows/Documentation.yml | 45 +++++++++++------------------ pyproject.toml | 2 +- 2 files changed, 18 insertions(+), 29 deletions(-) diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml index 39ee3fa..a5c0534 100644 --- a/.github/workflows/Documentation.yml +++ b/.github/workflows/Documentation.yml @@ -8,51 +8,40 @@ on: tags: '*' pull_request: -# sphinx-build doc _build permissions: - contents: write + contents: write + jobs: docs: runs-on: ubuntu-latest + steps: - uses: actions/checkout@v4 with: - lfs: 'true' + lfs: true fetch-depth: 0 - - uses: actions/setup-python@v3 - - name: Install dependencies - run: | - # pip install -r docs/requirements.txt - pip install -e .[docs] + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: "pip" - - name: Sphinx Build Develop + - name: Install dependencies run: | - git checkout develop - git fetch --all - git pull --all - cd ${{ github.workspace }}/docs - # make html - sphinx-multiversion source build/html + python -m pip install --upgrade pip + python -m pip install -e ".[docs]" + python --version + python -m pip show sphinx sphinx-multiversion - - name: Sphinx Build Main + - name: Build docs run: | - git checkout main - cd ${{ github.workspace }}/docs + cd docs sphinx-multiversion source build/html - # - name: Make symlinks - # run: | - # ln -sf ${{ github.workspace }}/build/html/main ${{ github.workspace }}/build/html/stable - # ln -sf ${{ github.workspace }}/build/html/develop ${{ github.workspace }}/build/html/dev - - name: Deploy uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.event_name == 'push' && ((github.ref == 'refs/heads/main') || (github.ref == 'refs/heads/develop'))}} + if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop') }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} - # publish_dir: docs/build/ - publish_dir: docs/build/html/ - # publish_dir: _build/ - # force_orphan: true + publish_dir: docs/build/html/ \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 99789cc..06151cd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -131,7 +131,7 @@ test = [ "flake8", ] docs = [ - "sphinx", + "sphinx<9", "furo", "sphinx-multiversion", ] From 1272dc9708551799c3d65745edf38adbd802431f Mon Sep 17 00:00:00 2001 From: Niklas Melton Date: Thu, 4 Jun 2026 14:12:21 -0500 Subject: [PATCH 2/4] make docs conf and workflow agree on branches to build on --- .github/workflows/Documentation.yml | 4 +++ docs/source/conf.py | 52 ++++++++--------------------- 2 files changed, 18 insertions(+), 38 deletions(-) diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml index a5c0534..560b101 100644 --- a/.github/workflows/Documentation.yml +++ b/.github/workflows/Documentation.yml @@ -26,6 +26,10 @@ jobs: python-version: "3.12" cache: "pip" + - name: Fetch all branches and tags + run: | + git fetch origin '+refs/heads/*:refs/remotes/origin/*' --tags --force + - name: Install dependencies run: | python -m pip install --upgrade pip diff --git a/docs/source/conf.py b/docs/source/conf.py index 2f7d26a..9b361a9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -31,8 +31,6 @@ 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', "sphinx_multiversion", - # 'sphinx.ext.autosectionlabel', - # 'sphinx_autopackagesummary', ] autosummary_generate_overwrite = True @@ -54,8 +52,6 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# html_theme = 'alabaster' -# html_theme = 'sphinx_rtd_theme' html_theme = 'furo' html_static_path = ['_static'] @@ -72,47 +68,27 @@ ], } -# html_css_files = [ -# 'css/rtd.css', -# ] - # -- Options for EPUB output epub_show_urls = 'footnote' -# Whitelist pattern for tags (set to None to ignore all tags) -# smv_tag_whitelist = r'^.*$' -# smv_tag_whitelist = r'v*' +# Ignore tags for now smv_tag_whitelist = None -# smv_tag_pattern = r'^v\d*\.\d*\.\d*$' -# smv_tag_pattern = r'^.*(?!alpha)$' - -# Whitelist pattern for branches (set to None to ignore all branches) -# smv_branch_whitelist = r'^.*$ -# smv_branch_whitelist = None -# smv_branch_whitelist = r'^(main|develop)$' -# smv_branch_whitelist = r'^self-host-docs$' -smv_branch_whitelist = r'^(main|develop)$' - -# Whitelist pattern for remotes (set to None to use local branches only) -smv_remote_whitelist = None - -# Pattern for released versions -# smv_released_pattern = r'^v.*$' -# smv_released_pattern = r'v\d*\.\d*\.\d*' + +# Build docs for main and develop, whether sphinx-multiversion sees them +# as local branches or as remote branches. +smv_branch_whitelist = r'^(origin/)?(main|develop)$' + +# Allow origin/main and origin/develop. +smv_remote_whitelist = r'^origin$' + +# No tags are being built, so this does not matter much right now. smv_released_pattern = r'^tags/.*$' -# Format for versioned output directories inside the build directory +# Use simple output directories: main, develop. smv_outputdir_format = '{ref.name}' -# Determines whether remote or local git branches/tags are preferred if their output dirs conflict -smv_prefer_remote_refs = False - -# # Skip param objects because of their weird rendering in docs -# def maybe_skip_member(app, what, name, obj, skip, options): -# # print app, what, name, obj, skip, options -# # if name == "" -# return True +# Prefer remote refs in CI, since GitHub Actions reliably has origin/main +# and origin/develop after fetching. +smv_prefer_remote_refs = True -# def setup(app): -# app.connect('autodoc-skip-member', maybe_skip_member) From acdfbc55714fa4472b3f4be61a73ec21bdaddacd Mon Sep 17 00:00:00 2001 From: Niklas Melton Date: Thu, 4 Jun 2026 14:16:21 -0500 Subject: [PATCH 3/4] remove tests for 3.7 and x86. 3.7 is deprecated. Extend tests through 3.15 --- .github/workflows/Test.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/Test.yml b/.github/workflows/Test.yml index 181e629..ec77b76 100644 --- a/.github/workflows/Test.yml +++ b/.github/workflows/Test.yml @@ -14,14 +14,13 @@ jobs: strategy: matrix: # Test on current Python LTS versions - python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"] + python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"] os: - ubuntu-latest # - macOS-latest # - windows-latest arch: - x64 - - x86 steps: - uses: actions/checkout@v3 From ee6fe577f67f6aaa1c9f96d6019b30289d0f1c35 Mon Sep 17 00:00:00 2001 From: Niklas Melton Date: Thu, 4 Jun 2026 14:18:21 -0500 Subject: [PATCH 4/4] remove tests for 3.15, not stable yet --- .github/workflows/Test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/Test.yml b/.github/workflows/Test.yml index ec77b76..bfacdde 100644 --- a/.github/workflows/Test.yml +++ b/.github/workflows/Test.yml @@ -14,7 +14,7 @@ jobs: strategy: matrix: # Test on current Python LTS versions - python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"] + python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"] os: - ubuntu-latest # - macOS-latest