CI testing of sphinx documentation
Open
Nobody has claimed this yet.
type: testing
- Dominant language
- C++
- Stars
- 287
- Forks
- 109
- Avg merge
- 4d 41m
- Merged PRs (30d)
- 5
Description
We should be enforcing warning-less sphinx build. Practice shows rST files tend to fall behind with code changes.
Steps:
- fix remaining errors and warnings in
sphinx_docstarget after latest Doc Day changes are all merged in; - add sphinx (and RTD theme) to either base Docker images or the TPL build (I think version differences are less severe there than in doxygen, but I may be horribly wrong);
- add a CTest test with a custom script that checks the output of
make sphinx_docscommand (this is needed because the command exits with 0 even in presence of errors). Adding-wor-Wtosphinx-buildmight be helpful if BLT allows. - add a (non-terminating) Stage 1 CI check that runs said test, or add to an existing check
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the sphinx_docs target and inspect how the current documentation build reports warnings and errors. Then review the CTest integration and Stage 1 CI checks, along with the base Docker images or TPL build configuration. Done means a warning-free Sphinx build is tested and the check runs in CI without terminating the stage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cmake, docker
- Domain
- build-system, ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100