"Recursion error" when building documentation with Sphinx >= 2.1

[hdiogenes]

$ make -C docs/ default doctest
make clean
rm -rf pyof.*
rm -rf _build/*
make dirhtml
sphinx-apidoc -o . ../pyof/ -d10 -M -T
Creating file ./pyof.rst.
Creating file ./pyof.foundation.rst.
Creating file ./pyof.v0x01.rst.
Creating file ./pyof.v0x01.asynchronous.rst.
Creating file ./pyof.v0x01.common.rst.
Creating file ./pyof.v0x01.controller2switch.rst.
Creating file ./pyof.v0x01.symmetric.rst.
Creating file ./pyof.v0x04.rst.
Creating file ./pyof.v0x04.asynchronous.rst.
Creating file ./pyof.v0x04.common.rst.
Creating file ./pyof.v0x04.controller2switch.rst.
Creating file ./pyof.v0x04.symmetric.rst.
#sed -i "/Submodules/,+1d" *.rst
#sed -i "/Subpackages/,+1d" *.rst
sphinx-build -b dirhtml -d _build/doctrees  -W . _build/dirhtml
Running Sphinx v2.1.2
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [dirhtml]: targets for 19 source files that are out of date
updating environment: 19 added, 0 changed, 0 removed
reading sources... [ 42%] pyof.foundation
Recursion error:
maximum recursion depth exceeded while calling a Python object

This can happen with very large or deeply nested source files.  You can carefully increase the default Python recursion limit of 1000 in conf.py with e.g.:
    import sys; sys.setrecursionlimit(1500)
make[1]: *** [dirhtml] Error 2
make: *** [default] Error 2

Older versions work:

$ pip install -U 'sphinx<2.1'
$ make -C docs/ default doctest
...
build succeeded.

[Niehaus]

By commenting the line 5 of docs Makefile SPHINXOPTS = -W you've got those warnings:

WARNING: error while formatting signature for pyof.foundation.base.GenericBitMask: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: maximum recursion depth exceeded while calling a Python object)
WARNING: error while formatting signature for pyof.v0x01.common.action.ActionType: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x01.common.flow_match.FlowWildCards: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x01.common.phy_port.PortConfig: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x01.common.phy_port.PortFeatures: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x01.common.phy_port.PortState: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x01.controller2switch.features_reply.Capabilities: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x01.controller2switch.flow_mod.FlowModFlags: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
/home/barbara/github/python-openflow/pyof/v0x04/common/flow_match.py:docstring of pyof.v0x04.common.flow_match.Match.get_field:5: WARNING: Field list ends without a blank line; unexpected unindent.
WARNING: error while formatting signature for pyof.v0x04.common.port.PortConfig: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x04.common.port.PortFeatures: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x04.common.port.PortState: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x04.controller2switch.features_reply.Capabilities: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x04.controller2switch.flow_mod.FlowModFlags: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x04.controller2switch.meter_mod.MeterFlags: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')
WARNING: error while formatting signature for pyof.v0x04.controller2switch.multipart_reply.GroupCapabilities: Handler <function record_typehints at 0x7f55f56d65e0> for event 'autodoc-process-signature' threw an exception (exception: '__signature__')

Which leads to remove the inheritance of metaclass=MetaBitMask from GenericBitMask, what reduces significantly the amount of warnings. Maybe this could mean that the problem is in the meta class MetaBitMask.

[hdiogenes]

After that, the only warning that is left is this:

pyof/v0x04/common/flow_match.py:docstring of pyof.v0x04.common.flow_match.Match.get_field:5: WARNING: Field list ends without a blank line

@Niehaus, please make a PR just commenting the SPHINXOPTS line and upgrading sphinx, then we can try to solve the metaclass problem later.