Documentation build errors should be flagged during build.

[pkienzle]

We are already building them on the Jenkins server, but the doc errors aren't visible unless you dig into the console output from the build.

Maybe better setuptools integration would help? Our doc builds are a little complicated since we are pulling in sasmodels and bumps documentation parts, so existing tools would require tweaking.

_Originally posted by @pkienzle in https://github.com/SasView/sasview/pull/1397/review_comment/create_

[butlerpd]

@pkienzle was this fixe by the #1430 PR (merged)? If so can we close the ticket? assigning to 5.0.3 for now but if not fixed, will probably move to 5.1

[pkienzle]

Here's the console output of the latest build on Jenkins:

https://jenkins.esss.dk/sasview-beta/job/SasView-Ubuntu1804/lastBuild/consoleFull

The link is to the latest build, so errors may have changed. Note that the docs are built a couple of times, with different warnings in each section.

Build 631 on 2020-04-26 was a "clean" build with the following warnings:

/home/sasview/anaconda3/envs/qt5_ubuntu/lib/python3.6/site-packages/sphinx/util/nodes.py:52: FutureWarning: 
   The iterable returned by Node.traverse()
   will become an iterator instead of a list in Docutils > 0.16.
  for classifier in reversed(node.parent.traverse(nodes.classifier)):
[repeated]

...

/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasmodels/sasmodels/compare.py:docstring of sasmodels.compare:87: WARNING: Unexpected indentation.

...

/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasmodels/doc/guide/plugin.rst:13: WARNING: undefined label: add/multiply models (if the link has no caption the label must precede a section header)

...

/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasmodels/sasmodels/compare.py:docstring of sasmodels.compare:87: WARNING: Unexpected indentation.

...

WARNING: autodoc: failed to import module 'sas.qtgui.Calculators.DataOperationUtilityPanel'; the following exception was raised:
Traceback (most recent call last):
  File "/home/sasview/anaconda3/envs/qt5_ubuntu/lib/python3.6/site-packages/sphinx/ext/autodoc/importer.py", line 140, in import_module
    __import__(modname)
  File "/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/src/sas/qtgui/Calculators/DataOperationUtilityPanel.py", line 11, in <module>
    from sas.qtgui.Plotting.Plotter import PlotterWidget
  File "/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/src/sas/qtgui/Plotting/Plotter.py", line 13, in <module>
    from sas.qtgui.Plotting.PlotterBase import PlotterBase
  File "/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/src/sas/qtgui/Plotting/PlotterBase.py", line 7, in <module>
    from matplotlib.backends.backend_qt5agg import FigureCanvasQTAgg as FigureCanvas
  File "/home/sasview/anaconda3/envs/qt5_ubuntu/lib/python3.6/site-packages/matplotlib/backends/backend_qt5agg.py", line 15, in <module>
    from .backend_qt5 import (
  File "/home/sasview/anaconda3/envs/qt5_ubuntu/lib/python3.6/site-packages/matplotlib/backends/backend_qt5.py", line 222, in <module>
    class FigureCanvasQT(QtWidgets.QWidget, FigureCanvasBase):
TypeError: metaclass conflict: the metaclass of a derived class must be a (non-strict) subclass of the metaclasses of all its bases
[repeated]

...

/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/src/sas/sascalc/pr/calc.py:docstring of sas.sascalc.pr.calc.positive_errors:10: WARNING: Field list ends without a blank line; unexpected unindent.
/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/src/sas/sascalc/pr/calc.py:docstring of sas.sascalc.pr.calc.positive_integral:10: WARNING: Field list ends without a blank line; unexpected unindent.

WARNING: autodoc: failed to import module 'sas.sasview.welcome_panel'; the following exception was raised:
No module named 'wx'
WARNING: autodoc: failed to import module 'sas.sasview.wxcruft'; the following exception was raised:
No module named 'wx'
/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/docs/sphinx-docs/source-temp/user/qtgui/Perspectives/Invariant/invariant_help.rst:13: WARNING: Duplicate substitution definition name: "Ang^-1".

/home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/docs/sphinx-docs/source-temp/user/sasgui/perspectives/file_converter/file_converter_help.rst:8: WARNING: duplicate label file_converter_tool, other instance in /home/sasview/Jenkins/workspace/SasView-Ubuntu1804/sasview/docs/sphinx-docs/source-temp/user/qtgui/Calculators/file_converter_help.rst
looking for now-outdated files... none found

Some of these can be easily fixed in the docs. Others will require configuration changes in the build or perhaps different packages.

[butlerpd]

@wpotrzebowski and @pkienzle - given that Jenkins is being "deprecated" in favor of github actions and that work on this front is the subject of a number of PR and issues, should we close this ticket as no longer helpful/useful?