[GRASS-dev] pygrass documentation

[Vaclav Petras]

On Mon, Apr 28, 2014 at 1:39 AM, Markus Neteler <neteler at osgeo.org> wrote:

> At this point we may consider to document all Python API in reST
> (rather than using doxygen for
> http://grass.osgeo.org/programming7/pygrasslib.html )
>

+1

Doxygen does not work well for Python and from what I understood on their
mailing list it will not get better any time soon [0, 2]. Doxygen is great
for C, C++ and others, Python support is only basic.

Moreover, it does not seem practical to have C API, Python API, and GUI
(+-API and internals) in one documentation. So, I'm for 3 different
documentations.

I'm not sure about merging Python API (including temporal) and PyGRASS. I
also think that we will loose possibility to link between the
documentations easily. And I'm also afraid of introducing another markup
(we have now HTML for doc and HTML+Markdown+Doxygen+Doxygen-LaTeX-like for
programming), although reStructuredText is almost Python standard. But
anyway, I think that using Sphinx and reStructuredText for Python will be
beneficial.

Vaclav


PS: Just a reminder: The ! at the beginning of docstring in Python which we
are using (to get Doxygen syntax working there) is undocumented feature and
is not officially supported [1] (I asked about that [2]).

[0]
http://doxygen.10944.n7.nabble.com/Mixed-C-and-Python-project-td5793.html
[1] http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#pythonblocks
[2]
http://doxygen.10944.n7.nabble.com/Python-docstrings-and-exclamation-mark-td4689.html
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20140428/80673885/attachment.html>