search

vovkos / doxyrest

A compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen and produces reStructuredText for the Python documentation generator Sphinx.
MIT License
306 stars 23 forks source link

Make it possible to reference using :any: role #37

Closed johanseland closed 3 years ago

johanseland commented 3 years ago

Would it be possible to ensure that the cref domain is loaded into the list of domains that is searched when using the RST :any: role?

Currently I must either use :cref:Foo::Bar or Foo::Bar if I enable the default role. However, I would like to be able to resolve Doxyrest generated references using e.g. :any:Foo::Bar

vovkos commented 3 years ago

Good point. The solution is to register a domain in the Sphinx extension. Then we can process the cref database when Sphinx is handling :any: links (essentially, it enumerates all registered domains and calls Domain.resolve_any_xref).

Please check the latest commit and let me know if it works for you.

johanseland commented 3 years ago

Thanks - I will try it out and give you feedback.

johanseland commented 3 years ago

I am happy to report that you patch works exactly as I wanted. Thank you so much and merry Christmas!

Just a little background on my motivation for this. I have some existing markdown material that I wish to cross-refer with Doxygen generated API references. I am using recommonmark for this, and if a markdown link does not matches any known url schemes it will try lookup using the any-role.

One caveat if anyone is stumbling upon this issue; you must ensure that you have set recommonmark.known_url_schemes, if not any C++ namespace entity will be matched as a URL and the lookup will not work.

vovkos commented 3 years ago

I personally try to avoid markdown as much as possible, only use reStructruredText -- even for GitHub READMEs ;) And inside RST I also prefer not to use the :any: role. But I know that the official Sphinx documentation recommends setting :any: as the default role, so your proposal totally made sense (and wasn't hard to implement).

Closing this issue.

Merry Christmas and Happy New Year to you too!