Doc: provide type aliases for common classes

[mdickinson]

This PR adds type aliases for expanding common classes, so that a type declaration like:

Parameters
------------
executor : TraitsExecutor

doesn't complain about the unknown class TraitsExecutor.

It also sets napoleon_preprocess_types = True, which in addition to expanding the aliases, prevents Napoleon / autodoc complaining about the "optional" in type signatures like "float, optional".

---

Update: we also add a nitpick_ignore_regex definition to let us ignore autodoc-generated references to base classes from Pyside2, Pyface and wx.

[mdickinson]

A somewhat unexpected test failure on macOS / Python 3.6:

======================================================================
FAIL: test_shutdown_timeout (traits_futures.tests.test_traits_process_executor.TestTraitsExecutor)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Users/runner/hostedtoolcache/Python/3.6.13/x64/lib/python3.6/site-packages/traits_futures/tests/traits_executor_tests.py", line 242, in test_shutdown_timeout
    self.assertLess(actual_timeout, 1.0)
AssertionError: 1.2805911269999797 not less than 1.0

Looks like IPC on the macOS runners runs very slowly indeed.

[mdickinson]

I'm still seeing warnings on my local machine.

Some of those are expected - this PR doesn't yet claim to eliminate all warnings. But it should be eliminating these ones:

c:\users\rporuri\work\github\ets\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.QObject
c:\users\rporuri\work\github\ets\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.QObject
c:\users\rporuri\work\github\ets\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.App
c:\users\rporuri\work\github\ets\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.EvtHandler
c:\users\rporuri\work\github\ets\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.Timer
c:\users\rporuri\work\github\ets\traits-futures\traits_futures\wx\pingee.py:docstring of traits_futures.wx.pingee.Pingee:1: WARNING: py:class reference target not found: wx.EvtHandler

What version of Sphinx are you using?

[rahulporuri]

Sigh. Even after pulling the latest changes, i'm still seeing the same errors mark :/ What do you think we should do here.

c:\users\rporuri\work\github\ets\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.QObject
c:\users\rporuri\work\github\ets\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.QObject
c:\users\rporuri\work\github\ets\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.App
c:\users\rporuri\work\github\ets\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.EvtHandler
c:\users\rporuri\work\github\ets\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.Timer
c:\users\rporuri\work\github\ets\traits-futures\traits_futures\wx\pingee.py:docstring of traits_futures.wx.pingee.Pingee:1: WARNING: py:class reference target not found: wx.EvtHandler

[mdickinson]

@rahulporuri What version of Sphinx are you using? It's noticeable that the wx classes being complained about aren't the same as I was seeing: I was seeing references of the form wx.core.....

[mdickinson]

@rahulporuri One last try. I'm guessing that you were using Sphinx 3.5.x. For me, this last change works with both Sphinx 3.5 and Sphinx >= 4.

I'm suspecting that the form of reference I was seeing in Sphinx 4 was actually due to a bug.

[rahulporuri]

For me, this last change works with both Sphinx 3.5 and Sphinx >= 4.

Sorry for the guessing game but I'm using the latest version of sphinx on edm - 3.5.4-2. Testing the latest changes.

[mdickinson]

Yes, sorry; it took me a while to realise you were using the ci commands.

[rahulporuri]

🎉 LGTM 🎉

[rahulporuri]

Yes, sorry; it took me a while to realise you were using the ci commands.

For future reference, I am almost always using the ci commands.