Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add linting for docs changes to CI #1624

Closed
conorsch opened this issue Mar 15, 2017 · 2 comments · Fixed by #1684
Closed

Add linting for docs changes to CI #1624

conorsch opened this issue Mar 15, 2017 · 2 comments · Fixed by #1684
Labels

Comments

@conorsch
Copy link
Contributor

When building the project documentation locally via make clean && sphinx-autobuild . _build/html, as specified in the developer docs, nearly two dozen warnings are displayed, generating more than a full screen of red text in the terminal on first run.

The warnings are mostly related to style, e.g. WARNING: Title underline too short, but some seem of greater concern: WARNING: duplicate label troubleshooting. The warnings still permit the docs to be built, but we should clean up those warnings and add linting to the CI config to guard against regressions. Particularly when overhauling the docs as described in #1544, we'll want to make sure the docs stay clean and consistent.

Haven't done much reading on best practice for linting Sphinx docs, but a quick and dirty method for detecting mistakes is: make clean && sphinx-build -Wn . _build/html. When run inside the docs/ folder of the project, any warnings will cause the build to exit non-zero.

@psivesely psivesely added the docs label Mar 15, 2017
@conorsch
Copy link
Contributor Author

conorsch commented Apr 4, 2017

We don't currently provide any developer-specific requirements file for installing the tooling necessary to test and configure the SecureDrop VMs. As of #1616 we're quite close with testinfra/requirements.txt, since that installs pytest and the like on the developer machine (preferably in a virtualenv), but we still only recommend installing sphinx for docs manipulation via a copy/pasted command from the developer docs. Will fold that logic into a dev-requirements.txt file, so it's installable under Travis as well, then update the dev docs to point to that file where appropriate (#1208).

@conorsch
Copy link
Contributor Author

conorsch commented May 3, 2017

Pushed up a feature branch add-linting-for-docs-warnings to add dead-simple docs linting to the Travis runs. If I did my math right, there will be failures on that branch until #1683 is merged; then the checks should pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants