..doxygenpage

[ferdymercury]

I can include files as ..doxygenfile, but I can not include Doxygen pages.

Would it be possible to include in the future a ..doxygenpage command?

The reason is that I have a cmake.dox file that I have included in my project, that documents my CMake flags. In my XML build, I get the files
xml/cmake_8dox.xml (this file is void)
xml/cmakePage.xml

I would like to include cmakePage.xml, because the other is void. However I cannot.
..doxygenfile:: cmake.dox
--> This works, but no output cause xml file is void

..doxygenfile:: cmakePage
--> WARNING: doxygenfile: Cannot find file "cmakePage

Ideally, one would need:
..doxygenpage:: cmake.dox

Thanks for this nice tool!

[vermeeren]

Breathe currently depends on Doxygen to output XML. So anything Doxygen can do but cannot output as XML Breathe will not be able to read. If I understand correctly by Doxygen page you refer to a separate .dox file that contains standalone documentation.

I think in nearly all cases when one is using Breathe+Sphinx rst is used for these kind of standalone pages. Using both Sphinx's rst and Doxygen's dox at the same time and integrated into a single Sphinx HTML build is something I have not heard of before, it seems messy to use multiple documentation systems like that.

PRs are welcome but because of the above I think this is a low priority enhancement, unless we find out a way to make doxygen output XML which will make things easier.

[ferdymercury]

I think I did not explain it clearly.

Doxygen generates a proper XML page, called cmakePage.xml. However, if I do ..doxygenfile cmake.dox, Breathe tries to look for cmake_8dox.xml, which is also generated by Doxygen and can be properly read by Breathe. The thing is that the info within this second xml file is void. The important info is in cmakePage.xml

What I am trying to suggest is a way to tell Breathe to look for cmakePage.xml instead, which is already there. Just the proper linking is missing. This could be done e.g. with a command like ..doxygenpage::

All what I am doing is because one of the INPUT files for Doxygen is a CMakeLists.txt, which I like also to document, to detail all compilation flags. See http://jesnault.fr/website/document-your-cmake-code-within-doxygen/

[ferdymercury]

Another more simple example. When I use /todo flags in Doxygen, they appear as a Page.

Doxygen generates also a todo.xml

A ..doxygenpage command would be useful to include this in sphinx+breathe.

[t-b]

@ferdymercury Your last comment is already an open issue, #258.

[vermeeren]

I think I understand what you mean now. Depending on the format/contents of cmakePage.xml this may be easy or hard to implement. The priority for now does not change though, there are a number of compatibility issues with recent Sphinx and also a bunch of bugs that need fixing.

[ferdymercury]

Thanks for the support. Please find attached two examples of XML pages in case it helps.

doxypage-examples.zip

[mwtoews]

I'm also looking at this issue. For example, a myfile.dox file with:

/*!

\page general_doc General documentation

\section blah Blah berg

Text.

*/

This content gets translated by doxygen to myfile.xml, but there is no easy way to get breathe to digest it. A doxygenpage directive would be handy!

[mwtoews]

Or better yet, see the existing example file page.doc. I don't see how this example is used, and I'm looking for it ...

[mwtoews]

The current output from the breathe test suite is partial. Here is the doxygen source:

/*! \page page1 A documentation page
  Leading text.
  \section sec An example section
  This page contains the subsections \ref subsection1 and \ref subsection2.
  For more info see page \ref page2.
  \subsection subsection1 The first subsection
  Text.
  \subsection subsection2 The second subsection
  More text.
*/

/*! \page page2 Another page
  Even more info.
*/

and breathe's sphinx-rendered HTML here:

Page

file page.doc

page page1
     Leading text.

page page2
     Even more info.

---

The expected output should look more like doxygen's HTML output:

A documentation page

Leading text.

An example section

This page contains the subsections The first subsection and The second subsection. For more info see page Another page.

The first subsection

Text.

The second subsection

More text.

[utzig]

This might have been implemented by #596

[vermeeren]

Indeed not entirely sure of the "page" here is the same as the xrefitem-based page the breathe doxygenpage directive now handles. Needs further investigation.

[utzig]

The current output from the breathe test suite is partial. Here is the doxygen source:

Yeah, yesterday I found out that \section is not supported. \section is only valid inside a \page and \page has only been supported since #596, so this was not a problem before, but I happen to have bumped into the same issue yesterday (as well as \table support), so I will probably implement this.

Indeed not entirely sure of the "page" here is the same as the xrefitem-based page the breathe doxygenpage directive now handles. Needs further investigation.

I am quite sure it is now! ;-)