Fix/Implement Doxygen filter for Python

[schuhschuh]

Issue by schuhschuh
Saturday Nov 09, 2013 at 18:02 GMT
Originally opened as cmake-basis/legacy#131

---

The Doxygen filter shall consider comment of the format

## @brief Desc.
#
# @param [in] arg Desc.
#
# @returns Return value.
def foo(arg):
    """Desc considered by sphinx-apidoc, but not the Doxygen filter."""
    return 42

The doc strings, on the other side, shall be ignored. These are better be processed by sphinx-apidoc and be formatted using reStructuredText instead of Doxygen commands/tags. This way, both documentation generators, Doxygen and Sphinx can exist side-by-side. Usually, a developer would for a particular module use either one of these documentation options, but rarely both.

Another possibility of including doc string formatted for Sphinx in the Doxygen output would be the preprocessing of these using rst2html as HTML code is allowed in Doxygen comments.
Reporter: Andreas Schuh
Assigned to: Andreas Schuh
Begin: 2012-06-16
Completed: 0

[schuhschuh]

Comment by schuhschuh
Sunday Nov 10, 2013 at 19:48 GMT

---

This requirement has to be re-evaluated given the improved Python support in Doxygen 1.8.

[schuhschuh]

Comment by ahundt
Saturday Nov 16, 2013 at 21:07 GMT

---

If there is integrated python support now, perhaps the task should be renamed "Integrate Doxygen Python Support"?

[schuhschuh]

Comment by schuhschuh
Saturday Nov 16, 2013 at 23:45 GMT

---

It must be evaluated how good the Python interpretation has become or what regarding Python source code documentation should be the standard as part of BASIS. I have a feeling there is still some good use for custom filters. Is it possible to document parameters using \param ? Can you use Doxygen commands + Markdown in Python documentation strings instead of special Doxygen comments ? Looking at the example at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#pythonblocks, the answers are that:

• Doxygen extracts the doc strings, but does not interpret any Doxygen commands within these. It does not display the documentation of the arguments in the same way as it would for C++, for example.
• Using the more Doxygen-like ## blocks which are also similar to how BASIS CMake modules are documented is possible and supports Doxygen commands + Markdown.

Thus, one needs to decide for one or the other as you unlikely want to document things twice. The first is the right Pythonic way of documentation and useful with tools made for Python. This documentation can also be retrieved in an interactive interpreter session which is quite useful. Also Sphinx can extract these and one may decide to use it within a reStructuredText document that is processed by Sphinx instead of Doxygen to generate HTML or PDF output.

There is a filter which supposedly allows the use of Doxygen commands in the doc strings. I had a look at at least one of these filters 1-2 years ago, including the native Python support of Doxygen at that time, and they all did not satisfy me completely. It is certainly worth, though, to reevaluate whether or not to implement an own Doxygen filter similar to the ones for CMake and Bash.

[schuhschuh]

Comment by ahundt
Sunday Nov 17, 2013 at 00:29 GMT

---

makes sense to me

[schuhschuh]

Comment by schuhschuh
Sunday Nov 17, 2013 at 00:49 GMT

---

I just read my initial issue comment and noticed that I actually meant to ignore the doc strings by the Doxygen filter, but instead separate the two documentations... one that goes into the Doxgyen generated API documentation, and one which goes into the Sphinx generated documents. The first can be referenced from the latter.

Not quite sure what I was thinking or if I am still on the same page :/

The rst2html option sounds still interesting, though. That way reStructuredText as in case of Sphinx can be used for documentation and yet included in the API documentation.