Address warnings in Sphinx build

[mdickinson]

There are a number of warnings in the Sphinx build; many of them are from the Napoleon machinery and can't easily be fixed or silenced, but some need to be acted on.

[mdickinson]

Related: sphinx-doc/sphinx#6861

[mdickinson]

many of them are from the Napoleon machinery and can't easily be fixed or silenced

This apparently is no longer true; the Sphinx bug above is closed. It took me a while to figure out from looking at that report and the PR that closed it what the fix is, but it's apparently to add something like:

napoleon_preprocess_types = True
napoleon_type_aliases = {"callable": ":class:`collections.abc.Callable`"}

to our conf.py. With this trick, we should be able to eliminate all of the warnings and turn on nitpicky mode in all the builds.

[mdickinson]

#400, #401, #402, #403, #404, #405 and #406 work towards this. After all of those are merged, there are 13 warnings remaining. The full documentation build output looks like this:

(traits-futures) mdickinson@mirzakhani traits-futures % git clean -ffxd
(traits-futures) mdickinson@mirzakhani traits-futures % python -m sphinx -b html -n docs/source docs/build
Running Sphinx v4.1.0
making output directory... done
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.rst.
File /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.api.rst already exists, skipping.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.background_call.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.background_iteration.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.background_progress.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.base_future.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.ets_event_loop.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.exception_handling.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.executor_states.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.future_states.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.i_event_loop.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.i_event_loop_helper.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.i_future.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.i_message_router.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.i_parallel_context.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.i_pingee.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.i_task_specification.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.multiprocessing_context.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.multiprocessing_router.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.multithreading_context.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.multithreading_router.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.traits_executor.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.version.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.wrappers.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.asyncio.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.asyncio.event_loop.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.asyncio.event_loop_helper.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.asyncio.pingee.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.qt.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.qt.event_loop.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.qt.event_loop_helper.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.qt.pingee.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.testing.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.testing.optional_dependencies.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.testing.test_assistant.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.wx.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.wx.event_loop.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.wx.event_loop_helper.rst.
Creating file /Users/mdickinson/Enthought/Projects/traits-futures/docs/source/api/traits_futures.wx.pingee.rst.
loading intersphinx inventory from https://docs.enthought.com/pyface/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.enthought.com/traits/objects.inv...
loading intersphinx inventory from https://docs.enthought.com/traitsui/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 49 source files that are out of date
updating environment: [new config] 49 added, 0 changed, 0 removed
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
/Users/mdickinson/.venvs/traits-futures/lib/python3.9/site-packages/traits/util/trait_documenter.py:80: RemovedInSphinx50Warning: The 'no_docstring' argument to TraitDocumenter.add_content() is deprecated.
  ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
reading sources... [100%] index                                                                                                                                                                             
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                              
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/qt/event_loop_helper.py:docstring of traits_futures.qt.event_loop_helper.AttributeSetter:1: WARNING: py:class reference target not found: pyface.qt.QtCore.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/qt/pingee.py:docstring of traits_futures.qt.pingee.Pingee:1: WARNING: py:class reference target not found: pyface.qt.QtCore.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/event_loop_helper.py:docstring of traits_futures.wx.event_loop_helper.AppForTesting:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/event_loop_helper.py:docstring of traits_futures.wx.event_loop_helper.AttributeSetter:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/event_loop_helper.py:docstring of traits_futures.wx.event_loop_helper.TimeoutTimer:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/pingee.py:docstring of traits_futures.wx.pingee.Pingee:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:65: WARNING: py:class reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:64: WARNING: py:meth reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant.assertEventuallyTrueInGui
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:64: WARNING: py:meth reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant.assertEventuallyTrueInGui
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:65: WARNING: py:class reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant
generating indices... genindex py-modindex done
highlighting module code... [100%] traits_futures.wx.pingee                                                                                                                                                 
writing additional pages... search done
copying images... [100%] guide/images/bad_square.png                                                                                                                                                        
copying downloadable files... [100%] ../guide/examples/quick_start.py                                                                                                                                       
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 13 warnings.

The HTML pages are in docs/build.

And the warnings, by themselves:

/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/qt/event_loop_helper.py:docstring of traits_futures.qt.event_loop_helper.AttributeSetter:1: WARNING: py:class reference target not found: pyface.qt.QtCore.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/qt/pingee.py:docstring of traits_futures.qt.pingee.Pingee:1: WARNING: py:class reference target not found: pyface.qt.QtCore.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/event_loop_helper.py:docstring of traits_futures.wx.event_loop_helper.AppForTesting:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/event_loop_helper.py:docstring of traits_futures.wx.event_loop_helper.AttributeSetter:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/event_loop_helper.py:docstring of traits_futures.wx.event_loop_helper.TimeoutTimer:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/traits_futures/wx/pingee.py:docstring of traits_futures.wx.pingee.Pingee:1: WARNING: py:class reference target not found: wx.
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:65: WARNING: py:class reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:64: WARNING: py:meth reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant.assertEventuallyTrueInGui
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:64: WARNING: py:meth reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant.assertEventuallyTrueInGui
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:65: WARNING: py:class reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant

[mdickinson]

The _task_sent and GuiTestAssistant warnings will likely be fixed as part of the other tasks scheduled for this release. Getting rid of the qt and wx-related warnings looks harder.

[mdickinson]

#400 has been updated with a way to ignore the Qt and wx-related warnings. With that PR, we're down to 7 warnings:

/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/advanced.rst:184: WARNING: py:meth reference target not found: BaseFuture._task_sent
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:65: WARNING: py:class reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:64: WARNING: py:meth reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant.assertEventuallyTrueInGui
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:64: WARNING: py:meth reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant.assertEventuallyTrueInGui
/Users/mdickinson/Enthought/Projects/traits-futures/docs/source/guide/testing.rst:65: WARNING: py:class reference target not found: pyface.ui.qt4.util.gui_test_assistant.GuiTestAssistant