Docs warning to error #3877
Merged
Docs warning to error #3877
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* master: Use napolean extension in docs to handle numpy docstrings too (SciTools#3871) Added whats new for pr3873 (SciTools#3874) linkcheck ignore for iris pull and issue url (SciTools#3873) Remove all local table of contents (SciTools#3872) Added whats new entry for pr3852 (SciTools#3854)
bjlittle
reviewed
Sep 22, 2020
| ``.readthedocs.yml``. | ||
| .. note:: In order to preserve a clean build for the html, all **warnings** | ||
| have been promoted to be **errors** to ensure they are addressed. | ||
| This **only** applies when ``make html`` is run. |
Member
There was a problem hiding this comment.
BTW in general, is it best to go with
.. note::
<content>
rather than
.. note:: <content>
Just curious if you have an opinion/care, or indeed, whether it really matters? (most likely not)
For most sphinx directives it's the former pattern rather than the latter 🤔
Contributor
Author
There was a problem hiding this comment.
Either is ok in my books. I prefer the latter as it helps the note be more visual - but this is my preference. If you have a particularly long note then the first option may be better as there is more text per line (due to no indentation)
…rror * upstream/master: Added include for common links file (SciTools#3876) Whats new for pr3871 (SciTools#3875)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
🚀 Pull Request
Description
Configured sphinx-build to promote warnings to errors when building the documentation via
make html.Updated the Makefile to use two new arguments:
-W. Turn warnings into errors. This means that the build stops at the first warning and sphinx-build exits with exit status 1.--keep-going. With -W option, keep going processing when getting warnings to the end of build, and sphinx-build exits with exit status 1.Also updated the
contributing to the documentationin the Iris docs to state that warnings are promoted to errors.For more info see https://www.sphinx-doc.org/en/master/man/sphinx-build.html?highlight=--keep-going#cmdoption-sphinx-build-W
Why do this?
Before the overhaul of the Iris docs (#3752), there were many warnings in the build but were not actively fixed as no error was raised and the travis task completed ok.
Why not promote all warnings to errors?
I believe the Travis jobs (of a task) will currently fail correctly for the following:
make gallerytestmake doctestmake linkcheckFor
make html-noplot(skip the gallery creation) it could be applied but this is usually used as a quick way to build the docs and themake htmlthat is part of the travis jobs (and can be run manually) will capture any issues anyway.Consult Iris pull request check list