Lint docs as part of CI
Closed this issue · 0 comments
conorsch commented
Feature Request
Description
The docs are automatically built from merged PRs and hosted on ReadTheDocs. We aren't testing the docs in any way via CI right now. We should:
- build the docs to confirm no failures
- lint the docs for common ReST errors
A patch such as the following would suffice:
.PHONY: docs-lint
docs-lint: ## Check documentation for common syntax errors.
# The `-W` option converts warnings to errors.
# The `-n` option enables "nit-picky" mode.
make -C docs/ clean && sphinx-build -Wn docs/ docs/_build/html
That example is lifted from similar work over in the SecureDrop repository. A new Makefile target such as the above should be appended to the CI config at circle.yml
.
User Stories
As as a developer, I want CI to catch common formatting mistakes prior to merging.
As a maintainer, I want to encourage well-structured documentation for the project, particularly for newcomers.