Possibility to link to API documents from another project

[markhh80]

Dear vovkos,

I tried doxyrest over the last couple days and I really like it so far. Thanks a lot for the effort you put into this great tool.

Is there a possibility, to reference content of the generated API rsts from another sphinx project?

What I would like to do is, have two projects:

global-project/ -- api/ (doxyrest rst output) -- manual/ (handwritten) index.rst conf.py

Both subprojects api/ and manual/ are referenced by index.rst so I am able to generate a single documentation containing both the API as well as the handwritten documentation. However: I would like to add links to some parts of the API (say, a class) by a simple hyperlink (no code extracts like sphinx/breathe) in the manual documentation.

Is this possible or a bad idea in general? I am aware of breathe and the doxygenclass directive but that is already too much for my needs.

All the best, Mark

[vovkos]

Hello Mark,

Thank you for your feedback and kind words; I really appreciate it. I'm happy when my tools are useful to other people.

Re linking to Doxyrest-generated documentation. As long as all source .rst files are part of the same Sphinx build tree, you can employ :ref: (standard Sphinx directive) or :cref (aka code-ref, a Doxyrest directive).

Using :ref: is pretty straightforward. Open the .rst file you want to link to and copy the ID from the very top of the file. For example, the top of an .rst file might look like:

.. index:: pair: enum; jnc_AccessKind
.. _doxid-group__module-item-decl_1gae37cf1474eba0491668ea2a32453731b:

The Doxygen ID is: doxid-group__module-item-decl_1gae37cf1474eba0491668ea2a32453731b. Now paste this ID into you :ref: directive and it will become a link, e.g.:

See :ref:`jnc_AccessKind <doxid-group__module-item-decl_1gae37cf1474eba0491668ea2a32453731b>` for more details.

The cref approach will require some setup, but should be easier to use if you need a lot of links (in which case copy-pasting Doxygen IDs becomes troublesome). In your doxyrest-config.lua specify:

CREF_DB = true

This will generate crefdb.py. You can find it next to all the other generated .rst files; copy it next to your conf.py. Now, in your documentation, you can link to API pages like this:

See :cref:`jnc_AccessKind` for more details.

You can simplify that even further by making :cref: the default role (of course, if the default role is not used for something else). In your conf.py add:

default_role = 'cref'

Now you can create links with:

See `jnc_AccessKind` for more details.

Let me know if that works for you.

[markhh80]

I tested the solutions and they all work well for me. Regarding "Copy crefdb.py to conf.py": I have multiple doxyrest projects referenced so I also have multiple crefdb.py files. Can this be setup somehow? If not I could still merge them into a single cref.dy/dict during the build process though.

Thanks a lot for your help!

EDIT: One more question: I was just wondering about the datastructure behind crefdb = {...}. I typically have a lot of redundant keys in it, like:

'DEBUG_LOG' : 'doxid-packagesignature_8cpp_1a571d51360926bac393fcf9c972a5ffa8',
'DEBUG_LOG' : 'doxid-paramaccessor_8cpp_1a571d51360926bac393fcf9c972a5ffa8',
'DEBUG_LOG' : 'doxid-archivehandler_8cpp_1a571d51360926bac393fcf9c972a5ffa8',

so any dictionary or JSON based merge approach fails given that keys must be unique. Is this structure intended?

[vovkos]

Hello Mark,

Apologies for a late reply.

1. Regarding multiple crefdb.py files -- I can make an adjustment to the Doxyrest extension for Sphinx to make it possible to explicitly specify a list of paths (instead of implicitly looking for crefdb.py next to the conf.py). This should solve the problem with multiple Doxyrest-generated docs being merged into a single build tree.

2. Regarding duplicate keys -- well, it's unavoidable when the same C/C++ identifier is being defined in multiple places (different projects/files). Once again, this crefdb.py is a map between C/C++ names and Doxygen IDs -- to enable :cref: role and make it possible creating links simply by specifying a C/C++ identifier.

Sometimes, of course, such mapping is ambiguous (just like in your case). But it's not such a big problem -- in this case, just don't use cref for these ambiguous idenitifiers, and instead of:

`DEBUG_LOG`

use something like:

:ref:`DEBUG_LOG <doxid-packagesignature_8cpp_1a571d51360926bac393fcf9c972a5ffa8>`

For unambiguous identifiers, you can keep using :cref: (as it's more convenient in most cases).

[vovkos]

Regarding multiple crefdb.py files. I decided that a better approach would be to simply enumerate all crefdb.py files in all subdirectories of the Sphinx source dir -- and merge all dictionaries together into one. That should be enough in most cases and doesn't require any extra "configuration" steps when building docs.

Try the latest commit and let me know if that works for you.

[markhh80]

Thank you! I will give it a try and get back to you soon. How do you deal with redundant keys though? Interpreting the file content as a dictionary will omit them. Were the redundancies supported in :cref: at all in the first place? In my example above, which entry would have been picked for :cref:DEBUG_LOG?

To fix the multiple files issue temporarily, I wrote a merge script interpreting the files as tuple lists and merging them line by line; not the best approach admittedly but worked for me. Will happily omit that though if your additions works for me too.

[markhh80]

I tested 79f589de88c889d0eb46068174f0241f4962a377 today and it works fine for my needs and project setup. Thanks again for your help!