Treat Sphinx warnings as errors when building docs on Travis #3770
Conversation
|
The plan is to add a script to the doc build process (because it is not complicated enough yet) that aggregates them by date and adds them to the top of the proper files. Supposedly IPython has such a script, but I could not find it last time I looked. The motivation for this was to avoid all of the rebases/messy merges that were required due to text conflicts in whats_new.rst and api_changes.rst. |
115bbfa to
e7515ec
Compare
e7515ec to
f0e03e0
Compare
|
Cool. Hopefully this will help us keep the improperly formatted docs away once and for all. Something to consider -- should "warnings as errors" be the default? Then building the docs locally will also make these problems obvious to developers before the changes hit Travis... |
|
Yes I would vote for changing the default to warnings as errors. But I thought it was better to go with a soft option in the beginning. |
DOC/BLD : Treat Sphinx warnings as errors when building docs on Travis
This pr sits on top of #3737 and #3768 which should be reviewed and merged before this one could be considered.
It does a number of things:
I think that it is a good idea to eliminate all the Sphinx warnings when building the docs. The fixes I have made to eliminate them resulted in a number of small fixes to the docs. Broken links, wrongly formatted text etc. The issues are much easier to fix right away in the pull request stage than later (especially since the tracebacks from autodoc are often misleading) So this should ensure that no new Sphinx issues are introduced into the docs.