You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The text was updated successfully, but these errors were encountered:
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).
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.
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 thedocs/
folder of the project, any warnings will cause the build to exit non-zero.The text was updated successfully, but these errors were encountered: