Iris Docs: Build has much less output now

[tkknight]

When building the documentation (uses sphinx-build) the typical output includes showing the files that are being read/written and a summary at the end.

Currently on master this output is now not being displayed. Some travis logs for reference:

• Expected output.
  • https://travis-ci.org/github/SciTools/iris/jobs/717339844#L1365. Note the [???%] progress update on the generating gallery, reading sources, writing output etc.
  • https://travis-ci.org/github/SciTools/iris/jobs/717339844#L1942. Note the summary showing copying files and that the build succeeded
• Current output from master as of today
  • https://travis-ci.org/github/SciTools/iris/jobs/718253890#L1381, has no [???%] progress updates and also part of the summary is missing
  • https://travis-ci.org/github/SciTools/iris/jobs/718253890#L1702. Note the summary is missing

The change in behaviour seems to be introduced via commit 556e71e

I have built the docs (make html) on master locally and have reproduced this. Additionally it seems that if there are .rst syntax warnings it is no longer displayed.

[tkknight]

ping @bjlittle

[tkknight]

Suspect the new logging file https://github.com/SciTools/iris/blob/master/lib/iris/etc/logging.yaml has changed the behaviour added via 556e71e

[tkknight]

I have successful got the output reinstated by explicitly (local branch atm) adding a reference to the sphinx in the https://github.com/SciTools/iris/blob/master/lib/iris/etc/logging.yaml file. The output looks different as it it using a formatter defined in this yaml file and not the default formatter for sphinx (I assume).

make html in src...
make[1]: Entering directory `/net/home/h06/itkt/projects/iris/docs/iris/src'
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v3.2.0
[conf.py] Iris Version = 3.0
[conf.py] Iris Release = 3.0.dev0
17-08-2020 16:46:11 sphinx.sphinx.util INFO - making output directory...
17-08-2020 16:46:11 sphinx.sphinx.util INFO - done
17-08-2020 16:46:11 sphinx.sphinx.ext.autosummary.generate INFO - [autosummary] generating autosummary for: copyright.rst, developers_guide/code_format.rst, developers_guide/contributing_documentation.rst, developers_guide/deprecations.rst, developers_guide/documenting/docstrings.rst, developers_guide/documenting/index.rst, developers_guide/documenting/rest_guide.rst, developers_guide/documenting/whats_new_contributions.rst, developers_guide/gitwash/configure_git.rst, developers_guide/gitwash/development_workflow.rst, ..., whatsnew/1.7.rst, whatsnew/1.8.rst, whatsnew/1.9.rst, whatsnew/2.0.rst, whatsnew/2.1.rst, whatsnew/2.2.rst, whatsnew/2.3.rst, whatsnew/2.4.rst, whatsnew/index.rst, whatsnew/latest.rst
17-08-2020 16:46:11 sphinx.sphinx.ext.intersphinx INFO - loading intersphinx inventory from http://scitools.org.uk/cartopy/docs/latest/objects.inv...
17-08-2020 16:46:11 sphinx.sphinx.ext.intersphinx INFO - loading intersphinx inventory from http://matplotlib.org/objects.inv...
17-08-2020 16:46:11 sphinx.sphinx.ext.intersphinx INFO - loading intersphinx inventory from http://docs.scipy.org/doc/numpy/objects.inv...
17-08-2020 16:46:11 sphinx.sphinx.ext.intersphinx INFO - loading intersphinx inventory from http://docs.python.org/2.7/objects.inv...
17-08-2020 16:46:11 sphinx.sphinx.ext.intersphinx INFO - loading intersphinx inventory from http://docs.scipy.org/doc/scipy/reference/objects.inv...
17-08-2020 16:46:12 sphinx.sphinx.ext.intersphinx INFO - intersphinx inventory has moved: http://scitools.org.uk/cartopy/docs/latest/objects.inv -> https://scitools.org.uk/cartopy/docs/latest/objects.inv
17-08-2020 16:46:12 sphinx.sphinx.ext.intersphinx INFO - intersphinx inventory has moved: http://docs.python.org/2.7/objects.inv -> https://docs.python.org/2.7/objects.inv
17-08-2020 16:46:12 sphinx.sphinx.ext.intersphinx INFO - intersphinx inventory has moved: http://matplotlib.org/objects.inv -> https://matplotlib.org/objects.inv
17-08-2020 16:46:12 sphinx.sphinx.ext.intersphinx INFO - intersphinx inventory has moved: http://docs.scipy.org/doc/scipy/reference/objects.inv -> https://docs.scipy.org/doc/scipy/reference/objects.inv
17-08-2020 16:46:12 sphinx.sphinx.ext.intersphinx INFO - intersphinx inventory has moved: http://docs.scipy.org/doc/numpy/objects.inv -> https://numpy.org/doc/stable/objects.inv
17-08-2020 16:46:12 sphinx.sphinx-gallery INFO - generating gallery...
17-08-2020 16:46:12 sphinx.sphinx.util INFO - generating gallery for generated/gallery/general... [  7%] plot_polar_stereo.py                                
17-08-2020 16:46:13 sphinx.sphinx.util INFO - generating gallery for generated/gallery/general... [ 15%] plot_global_map.py                                  

The (local) change to the https://github.com/SciTools/iris/blob/master/lib/iris/etc/logging.yaml file:

loggers:
  ...
  ...
  sphinx:
    level: INFO
    handlers: [console]

[tkknight]

Sphinx logging: https://www.sphinx-doc.org/en/master/_modules/sphinx/util/logging.html?highlight=logger#