Exception with latest breathe version

[fabratu]

Hi,

we use breathe in our project (NetworKit) to generate the documentation website. As of today (breathe version v4.29.1) the process fails with an assertion-error.

Exception occurred:
  File "/home/runner/work/networkit/networkit/pyenv/lib/python3.8/site-packages/breathe/renderer/sphinxrenderer.py", line 2113, in visit_docparamlist
    assert len(paramNameNodes) <= 1, paramNameNodes

Log from Github Actions: https://github.com/networkit/networkit/runs/2417500904#step:4:6624

We install breathe and all other components (link to environment) via pip3.

Link to sphinx conf.py.

Is there anything we have to change? Or should we pin the version to an older release?

Thanks in advance!

[vermeeren]

It seems like we hit the TODO from #675, see https://github.com/michaeljones/breathe/pull/675/files#diff-a325f86dbe6ccb9b9da00b730c7880d89cce7f5668023958e444fcaf80c0f6e0R2070

@fabratu Is it possible for you to provide the traceback? Either the file generated by CICD, or by adding -T to the sphinx-build command so it dumps the traceback to stdout. Probably -T is easiest adding it here https://github.com/networkit/networkit/blob/master/CMakeLists.txt#L659. I am curious to see what causes it.

[fabratu]

No problem. Added -T: https://github.com/fabratu/networkit/runs/2419355915?check_suite_focus=true#step:4:6646

[jakobandersen]

Damn, I tried to be careful when checking the XML structure. This assertion should be relaxed to a warning that something will look wrong.
To fix it we need to dig into the Doxygen XML and see what is going on for this case.
Is there a way to get to a state were we can just run doxygen and sphinx-build for your project? I tried just running .github/workflows/scripts/documentation.sh but I got

CMake Error at CMakeLists.txt:269 (set_target_properties):
  set_target_properties called with incorrect number of arguments.

[mloskot]

I also encountered the problem during build of https://github.com/nanodbc/nanodbc/ documentation

• Sphinx 3.5.4
• Breathe 4.29.1

sphinx-build -b html -d build/doctrees   . build/html
Running Sphinx v3.5.4
making output directory... done
...
uilding [mo]: targets for 0 po files that are out of date
building [html]: targets for 5 source files that are out of date
updating environment: [new config] 5 added, 0 changed, 0 removed
reading sources... [ 20%] api

Exception occurred:
  File "/usr/local/lib/python3.8/site-packages/breathe/renderer/sphinxrenderer.py", line 2113, in visit_docparamlist
    assert len(paramNameNodes) <= 1, paramNameNodes
AssertionError: [<breathe.parser.compound.docParamNameSub object at 0x7f8b11e86d60>, <breathe.parser.compound.docParamNameSub object at 0x7f8b11e86dc0>]
The full traceback has been saved in /tmp/sphinx-err-98xe1y6_.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [Makefile:62: html] Error 2

[fabratu]

Is there a way to get to a state were we can just run doxygen and sphinx-build for your project? I tried just running .github/workflows/scripts/documentation.sh but I got ...

If you want to execute it, you have to set env-variable CXX_STANDARD to at least 14 beforehand (that is at least how we run it). Alternatively you can set the variable directly in line 18 of documentation.sh:

cmake -DCMAKE_BUILD_TYPE=Debug -DNETWORKIT_CXX_STANDARD=14 -DNETWORKIT_WARNINGS=ON ..

I am also glad to assist in providing the necessary data:

1. Attached the output of doxygen, which is used for breathe breathe_projects = { 'NetworKit': '../build/doxyoutput/xml' }. This is from a local build, which is setup and run similar to what CI/CD does.
   networkit_doxygen_1.8.14.tar.gz
2. I am not sure what you mean what you mean with sphinx_build output. The make docs command in the end only triggers the sphinx_build command, which leads to the breathe-error.

[jakobandersen]

@mloskot, @fabratu, thanks! I found the source of the problem.
For nanodbc there is the unbind function with the comment

\throws index_range_error, database_error

which becomes the XML

<parameterlist kind="exception"><parameteritem>
   <parameternamelist>
      <parametername>index_range_error</parametername>
      <parametername>database_error</parametername>
   </parameternamelist>
   <parameterdescription>
      <para></para>
   </parameterdescription>
</parameteritem></parameterlist>

For networkit there is a very similar case for the constructor of GroupClosenessGrowShrink, where the comment is

@param first, last A range that contains the initial group of nodes.

which becomes the XML

<parameteritem>
   <parameternamelist>
      <parametername>first</parametername>
      <parametername>last</parametername>
   </parameternamelist>
   <parameterdescription>
      <para>A range that contains the initial group of nodes. </para></parameterdescription>
</parameteritem>

For \param (and \tparam) this is explicitly mentioned as allowed, and having a comma-separated list of names here should be fine (for now, this is not supported in raw rst).
There is also \retval where I think most Sphinx domains (at least C and C++) does not expect a name, only a description, but it looks like one can insert one anyway, so here a comma separated list should work for now.
For \exception I'm not sure this is intentionally supported by Doxygen. It will not work to generate a comma-separated list for Sphinx as it is being interpreted later to made into a link, so it is expected that the name is a single name, not a list (and again this is anyway not supported in raw rst). I suggest only rendering the first name and spit out a warning about the rest being dropped.