build(docs): update Starter Pack and add passthrough to docs Makefile

[medubelko]

Add aliases and passthrough Make targets provided by the docs project. With this, you can run make at the root of the project and access docs commands. The behaviour is:

• docs safely calls html
• docs-auto safely calls serve
• docs-clean safely calls clean
• docs-install calls vale-install and then calls root setup-docs
• docs-* passes through to all other doc targets

The goal is to keep the docs build nearly unedited. For this to work as of Starter Pack 1.3.1, the VALEDIR var in the docs Makefile must be changed to a conditional assignment (?=).

---

• I've followed the contribution guidelines.
• I've signed the CLA.
• I've successfully run make lint && make test.
• I've added or updated any relevant documentation.

[medubelko]

The workflows are failing:

WARNING: the sphinx_toolbox.latex extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

This wasn't a problem before because we allowed warnings, but the Starter Pack has fail-on-warning for both Sphinx builders. I'd rather not override it if we can avoid it. I'll look into whether we're using sphinx-toolbox in our projects aside from the collapse element. That one has a drop-in replacement.

[medubelko]

Removed sphinx-toolbox as it appears none of our repos are using it. Fixed RTD build and linting.

@jahn-junior @bepri @lengau Ready for review.

[bepri]

make docs-help fails on my machine currently:

Command output

❯ make docs-help
uv sync --no-dev "--group=docs"
      Built starcraft @ file:///home/imani/work/starbase
      Built rst2html==2020.7.4
Prepared 17 packages in 537ms
Uninstalled 69 packages in 80ms
Installed 64 packages in 14ms
 + accessible-pygments==0.0.5
 - anyio==4.8.0
 + anyio==4.12.0
 - apeye==1.4.1
 - apeye-core==1.1.5
 - autodocsumm==0.2.14
 - babel==2.16.0
 + babel==2.17.0
 - beautifulsoup4==4.12.3
 + beautifulsoup4==4.14.3
 - build==1.2.2.post1
 - cachecontrol==0.14.2
 + cairocffi==1.7.1
 + cairosvg==2.8.2
 - canonical-sphinx==0.3.0
 + canonical-sphinx==0.5.1
 - certifi==2024.12.14
 + certifi==2025.11.12
 + cffi==2.0.0
 - charset-normalizer==3.4.1
 + charset-normalizer==3.4.4
 - click==8.1.8
 + click==8.3.1
 - coverage==7.6.10
 + cssselect2==0.8.0
 - cssutils==2.11.1
 + defusedxml==0.7.1
 - dict2css==0.3.0.post1
 - domdf-python-tools==3.9.0
 - filelock==3.16.1
 - furo==2024.8.6
 + furo==2025.9.25
 + gitdb==4.0.12
 + gitpython==3.1.45
 - h11==0.14.0
 + h11==0.16.0
 - html5lib==1.1
 - idna==3.10
 + idna==3.11
 - iniconfig==2.0.0
 - jinja2==3.1.5
 + jinja2==3.1.6
 - lxml==5.3.0
 - markupsafe==3.0.2
 + markupsafe==3.0.3
 - mdit-py-plugins==0.4.2
 + mdit-py-plugins==0.5.0
 - more-itertools==10.6.0
 - msgpack==1.1.0
 - mypy==1.15.0
 - mypy-extensions==1.0.0
 - myst-parser==4.0.0
 + myst-parser==4.0.1
 - natsort==8.4.0
 - packaging==24.2
 + packaging==25.0
 + pillow==12.1.0
 - platformdirs==4.3.6
 - pluggy==1.5.0
 + pycparser==2.23
 - pydantic==2.10.5
 + pydantic==2.12.5
 - pydantic-core==2.27.2
 + pydantic-core==2.41.5
 - pygments==2.19.1
 + pygments==2.19.2
 - pyproject-hooks==1.2.0
 - pytest==8.3.4
 - pytest-cov==6.0.0
 - pytest-mock==3.14.0
 - pyyaml==6.0.2
 + pyyaml==6.0.3
 - regex==2024.11.6
 + regex==2025.11.3
 - requests==2.32.3
 + requests==2.32.5
 + rst2html==2020.7.4
 - ruamel-yaml==0.18.10
 - ruamel-yaml-clib==0.2.12
 - six==1.17.0
 + smmap==5.0.2
 - sniffio==1.3.1
 - snowballstemmer==2.2.0
 + snowballstemmer==3.0.1
 - soupsieve==2.6
 + soupsieve==2.8
 - sphinx-autodoc-typehints==2.3.0
 + sphinx-config-options==0.1.0
 + sphinx-contributor-listing==0.1.0
 + sphinx-copybutton==0.5.2
 + sphinx-design==0.6.1
 + sphinx-filtered-toctree==0.1.0
 - sphinx-jinja2-compat==0.3.0
 + sphinx-last-updated-by-git==0.3.8
 - sphinx-lint==1.0.0
 + sphinx-lint==1.0.2
 + sphinx-notfound-page==1.1.0
 - sphinx-prompt==1.8.0
 + sphinx-related-links==0.1.2
 + sphinx-reredirects==1.0.0
 + sphinx-roles==0.1.0
 + sphinx-sitemap==2.6.0
 + sphinx-terminal==1.0.3
 - sphinx-toolbox==3.8.1
 + sphinx-ubuntu-images==0.1.0
 + sphinx-youtube-links==0.1.0
 + sphinxcontrib-jquery==4.1
 + sphinxcontrib-svg2pdfconverter==2.0.0
 + sphinxext-opengraph==0.13.0
 - sphinxext-rediraffe==0.2.7
 + sphinxext-rediraffe==0.3.0
 - starcraft==0.0.post322+gcb7e449 (from file:///home/imani/canonical/starbase)
 + starcraft==0.0.post428+g718ff4e9e (from file:///home/imani/work/starbase)
 - starlette==0.45.2
 + starlette==0.50.0
 - tabulate==0.9.0
 + tinycss2==1.5.1
 - types-colorama==0.4.15.20240311
 - types-docutils==0.21.0.20241128
 - types-pygments==2.19.0.20250107
 - types-setuptools==75.8.0.20250110
 - typing-extensions==4.12.2
 + typing-extensions==4.15.0
 + typing-inspection==0.4.2
 - urllib3==2.3.0
 + urllib3==2.5.0
 - uvicorn==0.34.0
 + uvicorn==0.38.0
 + vale==3.13.0.0
 - watchfiles==1.0.4
 + watchfiles==1.1.1
 - websockets==14.2
 + websockets==15.0.1
make -C docs vale-install --no-print-directory
2026-01-13 10:15:31 - INFO - Cloning repository  to temporary directory: /tmp/tmpbssyyzsi
2026-01-13 10:15:31 - INFO - Copying /tmp/tmpbssyyzsi/styles/Canonical to /home/imani/work/starbase/docs/.sphinx/styles/Canonical
2026-01-13 10:15:31 - INFO - Copying /tmp/tmpbssyyzsi/styles/config/vocabularies/Canonical to /home/imani/work/starbase/docs/.sphinx/styles/config/vocabularies/Canonical
2026-01-13 10:15:31 - INFO - Copying /tmp/tmpbssyyzsi/styles/config/dictionaries to /home/imani/work/starbase/docs/.sphinx/styles/config/dictionaries
2026-01-13 10:15:31 - INFO - Copying /tmp/tmpbssyyzsi/vale.ini to /home/imani/work/starbase/docs/.sphinx/vale.ini
2026-01-13 10:15:31 - INFO - Cleaning up temporary directory: /tmp/tmpbssyyzsi
2026-01-13 10:15:31 - INFO - Download complete
. ../.venv/bin/activate; find ../.venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --version \;
find: ‘vale’: No such file or directory

[medubelko]

make docs-help fails on my machine currently:
Command output

It should be fixed with d7c5398

[bepri]

Thanks! For some reason, getting this to work required me to delete and remake my virtual environment first.

make docs-pymarkdownlnt doesn't work because it runs make docs-pymarkdownlnt-install, which runs pip install, which is rejected by uv-managed venvs.

make docs-spelling finds a lot of false positives.

Everything else seems to work! (unless you consider running npm install on my machine to be an issue)

[medubelko]

Thanks! For some reason, getting this to work required me to delete and remake my virtual environment first.

Hmm. That's an odd one. Let's discuss that offline.

make docs-pymarkdownlnt doesn't work because it runs make docs-pymarkdownlnt-install, which runs pip install, which is rejected by uv-managed venvs.

I'll noop this one, since we're never going to use it.

make docs-spelling finds a lot of false positives.

That's where the fun starts. :) I'll make the corrections in a follow-up.

[medubelko]

@bepri Rebased and ready for final approval.

I could recreate the venv issue with JJ but not Alex. There's no reason in principle for it to be happening. Switching to main, building, and then back to the branch doesn't replicate the issue.

[jahn-junior]

Leaving this as a blocking review due to issues running make commands from within the docs directory.