The current stable pybind11 is =dev-python/pybind11-2.5.0. Compiling with USE=doc succeeds with =dev-python/sphinx-2.4.4 and =dev-python/breathe-4.14.1, but fails with =dev-python/sphinx-3.2.1 and =dev-python/breathe-4.14.1. Error message: Exception occurred: File "/usr/lib/python3.7/site-packages/sphinx/domains/c.py", line 3166, in object_type raise NotImplementedError() NotImplementedError Another error message (using unstable =dev-python/breathe-4.22.1): Exception occurred: File "/usr/lib/python3.7/site-packages/breathe/renderer/sphinxrenderer.py", line 586, in run_directive rst_node = nodes[1] IndexError: list index out of range Another error message (using unstable =dev-python/breathe-4.22.1 and unstable =dev-python/pybind11-2.6.0 or =dev-python/pybind11-2.6.1): Extension error: Could not import extension sphinxcontrib.rsvgconverter (exception: No module named 'sphinxcontrib.rsvgconverter') Reproducible: Always Steps to Reproduce: 1.Attempt to build and install =dev-python/pybind11[doc] with =dev-python/sphinx-3.2.1 2. 3. Actual Results: Build fails (see error messages in description) Expected Results: Build fails, since there is a reason that =dev-python/pybind11[doc] blocks =dev-python/sphinx-3.2.1, but it would be nice if the build succeeded since =dev-python/sphinx-2.4.4 is becoming out of date.
First, I would like to apologize to any devs for opening a bug for a known issue. =dev-python/pybind11-2.5.0[doc], =dev-python/pybind11-2.6.0[doc], and =dev-python/pybind11-2.6.1[doc] currently depend on <dev-python/sphinx-3 to avoid this. However, <dev-python/sphinx-3 is going to start being a problem with newer versions of python being released (<dev-python/sphinx-3 does not support the newer versions), so I thought I would see what it would take to compile dev-python/pybind11[doc] with =dev-python/sphinx-3.2.1. I am not asking any devs to help me figure something out. I am merely reporting what I found. I really appreciate all the work the devs do and am hoping this helps somebody in the future when trying to update to >=dev-python/sphinx-3. The current stable pybind11 is =dev-python/pybind11-2.5.0. Compiling with USE=doc succeeds with =dev-python/sphinx-2.4.4 and =dev-python/breathe-4.14.1, but fails with =dev-python/sphinx-3.2.1 and =dev-python/breathe-4.14.1. The error message looks like this (=dev-python/pybind11-2.5.0[doc], with =dev-python/sphinx-3.2.1 and =dev-python/breathe-4.14.1): ----- BEGIN PASTE ----- reading sources... [ 89%] intro reading sources... [ 93%] limitations reading sources... [ 96%] reference Exception occurred: File "/usr/lib/python3.7/site-packages/sphinx/domains/c.py", line 3166, in object_type raise NotImplementedError() NotImplementedError The full traceback has been saved in ... ----- END PASTE ----- This issue has been reported here (pybind11 bug report 2404): https://github.com/pybind/pybind11/issues/2404 The error reported at the top is different than the NotImplementedError reported above, but a comment further down reports an error like the NotImplementedError. There are at least two problems described in that bug report. The first is that at least some versions of breathe are incompatible with =dev-python/sphinx-3.2.1. This bug report suggests >=dev-python/breathe-4.20.0 should be compatible with =dev-python/sphinx-3.2.1: https://github.com/michaeljones/breathe/issues/565 This older bug reports a similar issue with sphinx-3.0.0, fixed by >=dev-python/breathe-4.15.0: https://github.com/sphinx-doc/sphinx/issues/7424 Either way, it appears that =dev-python/breathe-4.14.1 is incompatible with =dev-python/sphinx-3.2.1, but the unstable =dev-python/breathe-4.22.1 is compatible. Compiling =dev-python/pybind11-2.5.0[doc] with =dev-python/sphinx-3.2.1 and =dev-python/breathe-4.22.1 gives the error message reported at the top of the pybind11 bug report 2404 given above: ----- BEGIN PASTE ----- reading sources... [ 89%] intro reading sources... [ 93%] limitations reading sources... [ 96%] reference Exception occurred: File "/usr/lib/python3.7/site-packages/breathe/renderer/sphinxrenderer.py", line 586, in run_directive rst_node = nodes[1] IndexError: list index out of range The full traceback has been saved in ... ----- END PASTE ----- This is the second issue pointed out in pybind11 bug report 2404. The API docs for pytypes does not work with newer versions of breathe. A comment in the bug report suggests commenting out the entire pytypes group in the documentation, but a less severe patch is already included in pybind11. The pull request is here: https://github.com/pybind/pybind11/pull/2220 The actual commit appears to be here: https://github.com/pybind/pybind11/commit/a3118130c6cf6307bf21fdb7ce9c00a71aec1360 This patch, included in =dev-python/pybind11-2.6.0 and =dev-python/pybind11-2.6.1 but not in =dev-python/pybind11-2.5.0, skips over two functions in pytypes that seem to trigger a bug in >=dev-python/breathe-4.17.0. This bug is known, and at least mentioned in breathe bug report 529 (but is probably distinct from the bug in that bug report): https://github.com/michaeljones/breathe/issues/529 However, the bug does not appear to be fixed yet.
First, the trivial fixes: Nothing needs to be done. dev-python/pybind11[doc] works with =dev-python/sphinx-2.4.4, and the pybind11 ebuilds should block =dev-python/sphinx-3.2.1, forcing =dev-python/sphinx-2.4.4. Also, dev-python/pybind11[-doc] does not have any problems. To get =dev-python/pybind11-2.5.0[doc] to work with =dev-python/sphinx-3.2.1, the dev-python/pybind11-2.5.0.ebuild needs to have the <dev-python/sphinx-3 line removed from the distutils_enable_sphinx call, =dev-python/breathe-4.22.1 needs to be stabilized (or keyworded) and installed, and the commit mentioned earlier that works around a bug in >=dev-python/breathe-4.17.0 should be applied as a patch to =dev-python/pybind11-2.5.0. There should be some mechanism to prevent =dev-python/breathe-4.14.1 being installed concurrently with =dev-python/sphinx-3.2.1. I suspect one of the following would work: 1) Add a <dev-python/sphinx-3 dependency to =dev-python/breathe-4.14.1 2) Add a !<dev-python-breathe-4.17 dependency to =dev-python/sphinx-3.2.1 On my system, dev-python/pybind11[doc] is the only thing that requires dev-python/breathe, so I chose to ``fix'' it there with this complicated addition to the pybind11 ebuild: 3) BDEPEND=" doc? ( || ( <dev-python/sphinx-3 dev-python/breathe ) ( >=dev-python/sphinx-3 >=dev-python/breathe-4.20 ) )" This last one does not really address the issue at its core, but it does keep the fixes for this issue localized to one package.
Created attachment 674596 [details, diff] Patch for =dev-python/pybind11-2.5.0 to work around bug in >=dev-python/breathe-4.17.0 This patch is a port of a commit from =dev-python/pybind11-2.6.0 that applies to =dev-python/pybind11-2.5.0, allowing =dev-python/pybind11-2.5.0[doc] to build with =dev-python/breathe-4.22.1, as described in Comment 1. The commit may be found here: https://github.com/pybind/pybind11/commit/a3118130c6cf6307bf21fdb7ce9c00a71aec1360
Alternatively, =dev-python/pybind11-2.6.0 and =dev-python/pybind11-2.6.1 already have the patch to work with >=dev-python/breathe-4.17.0. Another way to get =dev-python/pybind11[doc] to compile with =dev-python/sphinx-3.2.1 is to stabilize (or keyword) =dev-python/pybind11-2.6.0 or =dev-python/pybind11-2.6.1, remove the <dev-python/sphinx-3 line from the distutils_enable_sphinx call in the relevant ebuild, and install one of them with USE=doc instead. This still requires =dev-python/breathe-4.22.1, as described in Comment 2. Unfortunately, these now fail because they expect an extra sphinxcontrib package (two, actually, but the error only reports the first that is missing): ----- BEGIN PASTE ----- Running Sphinx v3.2.1 Extension error: Could not import extension sphinxcontrib.rsvgconverter (exception: No module named 'sphinxcontrib.rsvgconverter') ----- END PASTE ----- These sphinxcontrib packages were not installed on my system. I also did not see anything that looked like it would install these packages in the main portage tree. However, these sphinxcontrib packages do not appear to be necessary,so they can be patched out, allowing the package to build. It is not obvious if there is any negative effect from patching these out.
Created attachment 674599 [details, diff] Patch commenting out extra sphinxcontrib package requirements from =dev-python/pybind11-2.6.0 As described in Comment 4, =dev-python/pybind11-2.6.0[doc] and =dev-python/pybind11-2.6.1[doc] require sphinxcontrib packages that do not seem to be available in the main portage tree. These can still be built by commenting out those requirement. It is not obvious if this prevents portage from building all of the documentation, or if the sphinxcontrib packages are only required for non-HTML forms of documentation.
The bug has been closed via the following commit(s): https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=058cf235aafca1c6dd328700d212043fb98e1376 commit 058cf235aafca1c6dd328700d212043fb98e1376 Author: Michał Górny <mgorny@gentoo.org> AuthorDate: 2021-02-19 08:47:38 +0000 Commit: Michał Górny <mgorny@gentoo.org> CommitDate: 2021-02-19 08:47:38 +0000 dev-python/pybind11: Remove broken docs support Closes: https://bugs.gentoo.org/756283 Signed-off-by: Michał Górny <mgorny@gentoo.org> dev-python/pybind11/pybind11-2.6.0.ebuild | 4 ---- dev-python/pybind11/pybind11-2.6.1.ebuild | 4 ---- dev-python/pybind11/pybind11-2.6.2.ebuild | 4 ---- 3 files changed, 12 deletions(-)
