Documentation build failure on CI

[kitchoi]

Documentation build on master is failing with the following error:

Running Sphinx v3.2.0
making output directory... done
loading intersphinx inventory from https://docs.enthought.com/pyface/objects.inv...
loading intersphinx inventory from https://docs.enthought.com/traitsui/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 43 source files that are out of date
updating environment: [new config] 43 added, 0 changed, 0 removed
reading sources... [ 13%] traits_api_reference/ctraits                         
Extension error:
Handler <function _process_docstring at 0x04720B28> for event 'autodoc-process-docstring' threw an exception (exception: <method 'trait_items_event' of 'traits.ctraits.CHasTraits' objects> is not a module, class, method, function, traceback, frame, or code object)

If I downgrade to Sphinx 3.1.2, then the build passes.
Currently this is causing CI builds for new pull requests to fail.

[kitchoi]

Looks like this is related to this issue on Sphinx: sphinx-doc/sphinx#8074
There might be a bug fix release of Sphinx soon for this. We could either wait for it, but downgrade sphinx for now so we don't block PRs.

[mdickinson]

Re-opening: if the latest Sphinx from PyPI won't build the Traits documentation, that's a bug that should be investigated and fixed. (Even more so if the latest Sphinx from EDM won't build the Traits documentation.)

[mdickinson]

Looks like Sphinx 3.2.1 has been released. We should check that it builds the Traits docs successfully, and if so, we may want to revert the pinned Sphinx version.

[mdickinson]

On a broader topic, this does highlight once again the danger of unpinned dependent packages, even for something with as few dependencies as Traits. I'm wondering whether the right thing to do is to pin everything. It's not just about spurious PR failures caused by an upstream update - it's also about being able to recreate historical environments accurately when trying to reproduce old bugs, or when doing a git bisect to discover when a failure was introduced (or a bug was accidentally fixed!).

[kitchoi]

The PR title probably should have been "avoid Sphinx 3.2.0" after the change to !=3.2.0, we have not pinned a version, we should be getting the latest now that Sphinx 3.2.1 is released.

[mdickinson]

Okay, thanks. It probably makes sense to keep that, then, at least for now. I'd still like to double check that the build with 3.2.1 is okay before this issue gets reclosed.

By the way: why was the >= 2.1.0 version restriction removed? Is it no longer relevant?

[kitchoi]

why was the >= 2.1.0 version restriction removed?

Hmmm, it does look like it is no longer relevant to me, as CI is was getting Sphinx 3.1.2 without that restriction.

[mdickinson]

Right, but this isn't just about CI: the ">= 2.1.0" restriction is a statement that the doc build requires a version of Sphinx that's at least 2.1.0. As far as I know, that's still true: the doc build will fail with Sphinx versions earlier than 2.1.0. It's fine to remove that restriction on the basis that that version of Sphinx is so old that no-one could conceivably still want to use it, but that's independent of fixing the problem with 3.2.0. IOW, I don't think PR #1276 should have changed this. (But it's done now, and it's probably not worth the effort of reinstating.)

[mdickinson]

Recent CI builds (e.g., for #1296) have been using Sphinx 3.2.1 without issues, so I think we can close this.