Skip to content

Docs warning to error #3877

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.

Sign up for GitHub

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

Merged
bjlittle merged 8 commits into from
Sep 22, 2020
Merged

Docs warning to error #3877

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0d27059
Raised doc build warnings to errors (WIP)
tkknight Sep 21, 2020
fab8069
Merge branch 'master' into docs_warning_to_error
tkknight Sep 22, 2020
1bfe77d
Test doctest error
tkknight Sep 22, 2020
6eabc13
Undo test
tkknight Sep 22, 2020
b9b0e2e
Removed todo
tkknight Sep 22, 2020
5e215c1
Tweaked wording
tkknight Sep 22, 2020
074dd03
Fixed typo
tkknight Sep 22, 2020
07e3fba
Merge remote-tracking branch 'upstream/master' into docs_warning_to_e…
tkknight Sep 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/iris/src/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
SRCDIR = .

# See https://www.sphinx-doc.org/en/master/man/sphinx-build.html?highlight=--keep-going#cmdoption-sphinx-build-W
WARNING_TO_ERROR = -W --keep-going

# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
Expand Down Expand Up @@ -39,7 +42,7 @@ clean:
-rm -rf $(SRCDIR)/generated

html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
$(SPHINXBUILD) $(WARNING_TO_ERROR) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html"

Expand Down
17 changes: 10 additions & 7 deletions docs/iris/src/developers_guide/contributing_documentation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,11 +46,9 @@ If you wish to run a clean build you can run::

This is useful for a final test before committing your changes.

.. note:: In addition to the automated `travis-ci`_ build of the documentation,
the https://readthedocs.org/ service is also used. The configuration
of this held in a file in the root of the
`github Iris project <https://github.com/SciTools/iris>`_ named
``.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.
Copy link
Member

@bjlittle bjlittle Sep 22, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 🤔

Copy link
Contributor Author

@tkknight tkknight Sep 22, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)


.. _travis-ci: https://travis-ci.org/github/SciTools/iris

Expand Down Expand Up @@ -101,8 +99,13 @@ or ignore the url.
``spelling_word_list_filename``.


.. note:: All of the above tests are automatically run as part of the
`travis-ci`_ automated build.
.. note:: In addition to the automated `travis-ci`_ build of all the
documentation build options above, the
https://readthedocs.org/ service is also used. The configuration
of this held in a file in the root of the
`github Iris project <https://github.com/SciTools/iris>`_ named
``.readthedocs.yml``.


.. _conf.py: https://github.com/SciTools/iris/blob/master/docs/iris/src/conf.py

Expand Down