diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ae9cfdf..2777604 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,12 +1,32 @@ name: Documentation on: + pull_request: + paths: + - ".github/workflows/docs.yml" + - ".readthedocs.yaml" + - "docs/**" + - "images/**" + - "src/**" + - "tools/update_api_reference.py" + - "pyproject.toml" + - "setup.py" push: branches: - main + - master + paths: + - ".github/workflows/docs.yml" + - ".readthedocs.yaml" + - "docs/**" + - "images/**" + - "src/**" + - "tools/update_api_reference.py" + - "pyproject.toml" + - "setup.py" permissions: - contents: write + contents: read concurrency: group: docs-${{ github.ref }} @@ -18,14 +38,15 @@ jobs: steps: - name: Check out repository uses: actions/checkout@v4 - with: - fetch-depth: 0 - token: ${{ secrets.GITHUB_TOKEN }} - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.11" + cache: pip + cache-dependency-path: | + pyproject.toml + docs/requirements.txt - name: Install documentation dependencies run: | @@ -33,20 +54,10 @@ jobs: python -m pip install -e . python -m pip install -r docs/requirements.txt - - name: Update API reference record - run: python tools/update_api_reference.py + - name: Verify API reference is current + run: | + python tools/update_api_reference.py + git diff --exit-code -- docs/API_Reference.rst - name: Build Read the Docs site run: sphinx-build -b html -W --keep-going docs docs/_build/html - - - name: Commit API reference updates - run: | - if git diff --quiet -- docs/API_Reference.rst; then - echo "API reference is already current." - exit 0 - fi - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - git add docs/API_Reference.rst - git commit -m "docs: update API reference" - git push diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 5e15702..7393263 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -3,7 +3,7 @@ version: 2 build: os: ubuntu-24.04 tools: - python: "3.10" + python: "3.11" sphinx: configuration: docs/conf.py diff --git a/docs/API_Reference.rst b/docs/API_Reference.rst index eb21fda..122da37 100644 --- a/docs/API_Reference.rst +++ b/docs/API_Reference.rst @@ -358,6 +358,7 @@ buildcompiler.abstract_translator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: buildcompiler.abstract_translator + :no-index: :members: :undoc-members: :show-inheritance: diff --git a/docs/requirements.txt b/docs/requirements.txt index 9103101..1f3942c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,2 @@ -sphinx>=7 +sphinx>=7,<9 furo>=2024.1.29 diff --git a/tools/update_api_reference.py b/tools/update_api_reference.py index 5cd8053..52a5b8d 100644 --- a/tools/update_api_reference.py +++ b/tools/update_api_reference.py @@ -32,6 +32,7 @@ } EXCLUDED_MODULES = {"buildcompiler.__init__"} +NO_INDEX_MODULES = {"buildcompiler.abstract_translator"} def underline(text: str, char: str = "=") -> str: @@ -61,16 +62,21 @@ def modules_for_section(modules: list[str], package: str) -> list[str]: def render_module(name: str) -> list[str]: - return [ + lines = [ name, underline(name, "~"), "", f".. automodule:: {name}", + ] + if name in NO_INDEX_MODULES: + lines.append(" :no-index:") + lines.extend([ " :members:", " :undoc-members:", " :show-inheritance:", "", - ] + ]) + return lines def render_api_reference() -> str: