diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0a882d39..ce0079a5 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -98,14 +98,20 @@ $ tox run -e docs-watch This will build the documentation, watch for changes, and rebuild it whenever you save a file. -To just build the documentation and run doctests, use: +To just build the documentation and exit immediately use: ```console -$ tox run -e docs +$ tox run -e docs-build ``` You will find the built documentation in `docs/_build/html`. +To run doctests: + +```console +$ tox run -e docs-doctests +``` + ## Code diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 33956988..81895d74 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -172,7 +172,7 @@ jobs: if: ${{ failure() }} docs: - name: Build docs & run doctests + name: Run doctests & render changelog runs-on: ubuntu-latest needs: build-package steps: @@ -188,7 +188,7 @@ jobs: python-version: "3.13" - uses: hynek/setup-cached-uv@v2 - - run: uvx --with=tox-uv tox run -e docs,changelog + - run: uvx --with=tox-uv tox run -e docs-doctests,changelog pyright: name: Check types using pyright diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9bcdc4bc..d58ce338 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,18 +7,15 @@ build: # Keep version in sync with tox.ini/docs and ci.yml/docs. python: "3.13" jobs: - # Need the tags to calculate the version (sometimes). - post_checkout: + create_environment: + # Need the tags to calculate the version (sometimes). - git fetch --tags - # Replace versions in sponsor URLs. - pre_build: - - python -Im pip install tox-uv - - python -Im tox run -e docs-sponsors + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest -python: - install: - - method: pip - path: . - extra_requirements: - - docs + build: + html: + - uvx --with tox-uv tox run -e docs-sponsors + - uvx --with tox-uv tox run -e docs-build -- $READTHEDOCS_OUTPUT diff --git a/tox.ini b/tox.ini index 3fff3a2b..f39de7e3 100644 --- a/tox.ini +++ b/tox.ini @@ -6,7 +6,7 @@ env_list = py3{10,11,12,13}-mypy, pypy3-tests, pyright, - docs{,-sponsors}, + docs-{sponsors,doctests}, changelog, coverage-report @@ -64,19 +64,19 @@ pass_env = commands = pytest --codspeed -n auto bench/test_benchmarks.py -[testenv:docs] -# Keep base_python in-sync with ci.yml/docs and .readthedocs.yaml. +[testenv:docs-{build,doctests,linkcheck}] +# Keep base_python in sync with ci.yml/docs and .readthedocs.yaml. base_python = py313 extras = docs commands = - sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html - sphinx-build -n -T -W -b doctest -d {envtmpdir}/doctrees docs docs/_build/html - + build: sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs {posargs:docs/_build/}html + doctests: sphinx-build -n -T -W -b doctest -d {envtmpdir}/doctrees docs {posargs:docs/_build/}html + linkcheck: sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html [testenv:docs-watch] package = editable -base_python = {[testenv:docs]base_python} -extras = {[testenv:docs]extras} +base_python = {[testenv:docs-build]base_python} +extras = {[testenv:docs-build]extras} deps = watchfiles commands = watchfiles \ @@ -85,14 +85,6 @@ commands = src \ docs - -[testenv:docs-linkcheck] -package = editable -base_python = {[testenv:docs]base_python} -extras = {[testenv:docs]extras} -commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html - - [testenv:docs-sponsors] description = Ensure sponsor logos are up to date. deps = cogapp