CI: check rst syntax in [sanity]
What
Adds a job to the sanity stage that checks the syntax of restructure text files (.rst files).
Why
To avoid silly errors like this:
- https://gitlab.com/tezos/tezos/-/jobs/7754138569
- https://gitlab.com/tezos/tezos/-/jobs/7761533115#L291
causing merge-train pileups like this:

How
- add a new target
make -C docs sphinx-check
It allows to run sphinx (to check syntax) without actually writing any
output files (using --builder dummy). However, to run sphinx, we
must ensure the generated input files exist (like the manuals of
binaries). I took a very manual approach to this, having the target
manually create them.
- build this target in a new CI job.
Manually testing the MR
Locally
- Run
make -C docs sphinx-checklocally. - Introduce an error in an rst file (check the links above for inspiration)
- Try running it again.
In the CI
Check out the job. I ran it once with a phony error:
https://gitlab.com/tezos/tezos/-/jobs/7764802321
and once without phony error:
https://gitlab.com/tezos/tezos/-/jobs/7764865899
Checklist
-
Document the interface of any function added or modified (see the coding guidelines) -
Document any change to the user interface, including configuration parameters (see node configuration) -
Provide automatic testing (see the testing guide). -
For new features and bug fixes, add an item in the appropriate changelog ( docs/protocols/alpha.rstfor the protocol and the environment,CHANGES.rstat the root of the repository for everything else). -
Select suitable reviewers using the Reviewersfield below. -
Select as Assigneethe next person who should take action on that MR
Edited by Arvid Jakobsson