Cross-referencing to a doxygenfile from Sphinx

[ZedThree]

I'd like to link to a doxygenfile directive from Sphinx, but I can't find anything that does this. Sphinx supports cross-referencing to various declaration types -- file is missing, so is this something that needs to be done on the Sphinx side? Or have I just missed something?

As a note, I've generated the documentation using breathe-apidoc. A workaround would be to have that generate a section label which could be linked to with :ref:, which would be pretty easy to do.

[vermeeren]

I think it is not possible for Sphinx to "fix" this, since a file isn't really a C/C++ type or anything like that.

However, apidoc could be modified to automatically generate section labels above the page header for file types.

So that

File add.h
==========

.. doxygenfile:: add.h

Would turn into

.. _apidoc_file_add.h:

File add.h
==========

.. doxygenfile:: add.h

or similar.

A potential problem would be when there are multiple files with the same name in different directories. Using the full path should fix that however. What would you like to see?

[ZedThree]

Would using the same name that is given to the doxygenfile directive work? Presumably that has to be "unique enough" for it to be resolved in the first place?

[vermeeren]

You are right, that indeed must be unique enough. A possible implementation of #321 may solve this issue too, though it is mainly about generating some index instead of being able to reference directly in other RST.

What do you think about 321? Would it fulfil your use case or would you rather be able to reference to a page directly without generating an index?

[ZedThree]

I was hoping to be able to just reference a page directly, something like this:

Function `add` can be found in :ref:`apidoc_file_add.h`

Currently, I'm linking directly to the rst file itself:

Function `add` can be found in :doc:`add.h<../_breathe_autogen/file/add_8h>`:

which is not the worst thing in the world, but feels a little fragile, along with having to know the doxygen-encoded name of the file.

Your suggestion of generating the section labels would be enough for my use case.

[jakobandersen]

How about the following solution?

1. Breathe annotates the symbols created by the Sphinx C++ domain with additional data (not sure how difficult this is).
2. Sphinx exposes the symbol lookup functionality in a prettier way so Breathe can use it (small change).
3. Breathe gets a new role (e.g.,:breathe:fileof:`add`) that uses the same symbol lookup that the Sphinx roles use to find the internal symbol. A cross-reference is inserted with text from Breathe and the docname from the found symbol.

[vermeeren]

@ZedThree making apidoc creating per-page labels should be pretty easy, but do think @jakobandersen 's proposal will be a lot more flexible since it will probably also support linking to a specific class/func/etc on the destination page rather than just the page itself.

[ZedThree]

That would also work for me! :+1:

[t-b]

@ZedThree I've hacked sphinx labels into the rst files which breathe-apidoc generates.

The code is

for i in `ls group/group_*.rst`
do
  name=$(sed -e '$!d' -e 's/.*doxygengroup:: \(.*\)$/\1/' $i)
  sed -i "1s/^/.. _Group ${name}:\n\n/" $i
done

for i in `ls file/*.rst`
do
  name=$(sed -e '$!d' -e 's/.*doxygenfile:: \(.*\)$/\1/' $i)
  sed -i "1s/^/.. _File ${name}:\n\n/" $i
done

not nice but it works so far.

[AntoinePrv]

I stumble upon this issue when moving from a manual list of

.. doxygenfunction:: xt::foo

.. doxygenfunction:: xt::bar

.. doxygenfunction:: xt::baz

to

.. doxygengroup:: xt_group

All previous references to :cpp:func:`xt::foo` broke. One of two options was

• Either use :cpp:func:`foo`, which made it difficult to avoid mistakes when mixing both

• Or use

  .. cpp:namespace-push:: xt
  
  .. doxygengroup:: xt_group