Skip to content

Build documentation on every diff

Currently, the documentation is only built once a day with no notification, so it's easy to let typos slip through.

It should be part of the test suite. Options (ordered from easier to most efficient):

  1. naively clone all of swh-environment + the current diff and build swh-docs with tox -e sphinx-dev. this takes 5-10 minutes, which is more than the build time of any single repo, because it needs to install all the deps and sphinx has no cache
  2. have some base state with all the dependencies installed (and possibly sphinx's cache warmed up), eg. generated by the daily cron; then just apply the current Diff, re-run its setup, and make html.
  3. only build the local documentation of the repo, and find a way to ignore references to other repositories. (This will also hide typos in internal references...)
  4. only build the local documentation of the repo, but migrate all repos to use inter-sphinx, so building the local repo can check all references are valid. But have about 20 sphinx instances interconnected like this requires migrating all references and keeping them in sync

Personally I have a preference for option 2.


Migrated from T3258 (view on Phabricator)

To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information