:need: role is not working inside doxygen comment

[maxlutz98]

Hi,

I use doxygen + breathe + sphinx + sphinx-needs for documentation of a c project.

I ran into a problem the last few days. A simple reference to a need with the :need: role is not possible inside a rst enviornment in the doxygen comment.

Error:

Running Sphinx v4.4.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
node_type=memberdef[ 50%] docs/breathe_issue
  node_type=sectiondef
  node_type=compounddef
  node_type=doxygendef
  node_type=compound
  node_type=doxygen
  node_type=fakeparent
  res=[]
Running directive: .. c:function::  void example_function (void)

Exception occurred:
  File "C:\environments\sphinx_conda_env\lib\site-packages\docutils\nodes.py", line 2044, in unknown_visit
    raise NotImplementedError(
NotImplementedError: <class 'breathe.renderer.sphinxrenderer.NodeFinder'> visiting unknown node type: NeedRef
The full traceback has been saved in C:\Users\max\AppData\Local\Temp\sphinx-err-ir0m7_1p.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!

Logs:
sphinx-err-ir0m7_1p.log

Used rst code:

.. _breatheissue:

Breathe Issue
=============

.. req:: Example requirement
    :id: REQ_05252
    :collapse: True

    This is the requirement, the comment in function shall link to.


.. doxygenfunction:: example_function
    :project: example

C code + doxygen comment:

//----------------------------------------------------------------------------
//! This is an example for the breathe issue.
//!
//! This function resolves @rstinline :need:`REQ_05252`. @endrst
//!
//! This points to the heading of the issue page: @rstinline :ref:`Link <breatheissue>`. @endrst
//----------------------------------------------------------------------------
void example_function(void);

I also added some example of the :ref: role. This is working fine if the build is successful (the not working :need: role is blocking build).

[2bndy5]

@arwedus recently reported that breathe works with sphinx-needs. Maybe there's an additional requirement? Did you put sphinx_needs before breathe in the extensions list located in conf.py?

[maxlutz98]

Yes, sphinx-needs is before breathe in the extensions list.

The other features are working fine. E.g.: the following generates a requirement in the doxygen description as intended:

//----------------------------------------------------------------------------
//! This is an example for the breathe issue.
//! 
//! @rst
//! .. req:: Test
//!     :tags: example
//!
//!     This is a requirement example for sphinx-needs compatibility with breathe.
//! @endrst
//!
//! This points to the heading of the issue page: @rstinline :ref:`Link <breatheissue>`. @endrst
//----------------------------------------------------------------------------
void example_function(void);

The output is:

But as soon as I add this inline command :need: like in the initial example, I get errors in compilation.

[jakobandersen]

I can't immediately reproduce the error on my side. Which version of docutils are you using?
I used the C++ and RST you posted, sphinxcontrib-needs v0.7.5 via pip, and 'sphinxcontrib.needs' in the extension list. My docutils version is 0.17.1 (via pip).

[maxlutz98]

I also had docutils 0.17.1. I gave it a try with docutils 0.18.1 today, too.
Probably, I missed something in the explanation.
Thus, I made an example containing all required files and a requirements.txt with all tools installed in my environment for that try:
https://github.com/maxlutz98/breathe-example

I added the execution steps to the README.

[2bndy5]

Ok, I was able to reproduce this with the linked repo from #807 (comment)

Reproducible also if you reduce the requirements.txt to

breathe==4.33.1
sphinx-rtd-theme==1.0.0
sphinxcontrib-needs==0.7.5
sphinxcontrib-plantuml==0.22

I was also able to reproduce it with breathe rolled back to v4.31.0 and v4.32.0

[jakobandersen]

Thanks, that helped reproduce it. Can you try with #812? It seems to fix it in my local test.

[2bndy5]

I can confirm #812 fixes the problem.

[jakobandersen]

@2bndy5, very nice, thanks!

[maxlutz98]

Thanks for your support!