[GRASS-dev] sphinx python documentation

[Vaclav Petras]

Hi Luca,

that's great that you are working on that.

On Tue, May 27, 2014 at 3:58 AM, Luca Delucchi <lucadeluge at gmail.com> wrote:

> I everybody,
>
> In the last days some improvements were done on pygrass documentation side
> [0].
>
> I would like to ask you:
>
> - what do you think about extend sphinx documentation to all python
> library of GRASS?
>

Yes. Sphinx for the whole lib/python (grass.*). I'm not sure if additional
separate for PyGRASS would make sense, probably not. Then it would be nice
to have Sphinx for GUI (gui/wxpython).

Then I would disable all Python things (lib/python and gui/wxpython, the
later for sure) in Doxygen because especially GUI creates a mess in
Doxygen. It seems that Doxygen does not handle well all the things about
Python modules, packages (especially if lib/python/* is changed into
grass.*) and other Python features.

So than we would have tree documentations. Doxygen for C libraries, one
Sphinx for Python libraries and one Sphinx for GUI.

- could I replace doxigen instruction with sphinx instruction in
> pygrass docstrings? (for example replace @param with :param)
>
> Yes. And remove the exclamation marks at the beginning of docstrings
("""!...). (They are just using some undocumented Doxygen feature to enable
processing of commands instead of using verbatim text for docstrings.)


On Tue, May 27, 2014 at 4:17 AM, Luca Delucchi <lucadeluge at gmail.com> wrote:
On 27 May 2014 10:08, Martin Landa <landa.martin at gmail.com> wrote:
> >
> > wouldn't be possible to use syntax which understands both sphinx and
doxygen?
> >
> I don't think it is possible, but I don't know doxygen at all. Vaclav
> maybe know something more....

No, it is not possible. And I would probably be against even if it would be
possible.

Explanations:

I don't say that the proposed solution is perfect but I was following this
issue for more than a year and there is no better solution. The only
official support of in Doxygen commands in Python are commands in comments
(# ...). Docstrings are supposed to be copied as verbatim. The exclamation
mark we are using is undocumented feature. reStructured text is almost
standard for Python docstrings and is not supported in Doxygen and they
does not seem to implement this support any time soon (see some other posts
on this topic or my emails to doxygen mailing list).

It would be possible to have everything in Doxygen syntax and generate
Sphinx from that using Breathe but this is not what we want. We want a tool
which understands Python (that's Sphinx) and documentation style and syntax
in code which works nicely (tools, editors) in Python world (that's
reSturcturedText).

If the goal is to have everything in Doxygen-generated manual, I would say
that we would need Sphinx anyway as a primary manual (that's what we are
having this discussion) and Doxygen syntax would have to be generated from
Python code with Sphinx/reStructuredText syntax in docstrings. This is
possible in theory but we would have to create the conversion tool.

Feel free to ask additional question, I'll try to answer.


> [0] http://grass.osgeo.org/grass71/manuals/pygrass/index.html
>

Nice, perhaps bit too conservative design but fits to GRASS manual nicely.
I wish to have something similar for Doxygen but I'm afraid of maintenance
issues.

Vaclav

>
> --
> ciao
> Luca
>
> http://gis.cri.fmach.it/delucchi/
> www.lucadelu.org
> _______________________________________________
> grass-dev mailing list
> grass-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/grass-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20140527/21c113d8/attachment.html>