[GRASS-dev] pygrass documentation

[Vaclav Petras]

Hi, was browsing through Python parts (lib/python and gui) in Doxygen
documentation and I got the impression that the Python support in
Doxygen is very bad, especially for more advanced things (e.g.,
classes and functions are ok but properties do not) but also some
basic things are badly interpreted (different files in different
directories in gui are merged into the one module).

For now, I would leave pygrass doc in the ReST (both the py and rst files).

I will try to set Doxygen to find and use rst files but obviously the
result will be bad. Maybe there is some converter from rst into
markdown which can be used as a filter for rst files in Doxygen.

For the future, we will see. Having two docs, one Sphinx for Python
and one Doxygen for C/C++, is one solution but probably not easy (it
would be similar to having manual in custom HTML pages and Sphinx).
Improvements in Doxygen itself and/or filters for ReST would be very
beneficial for us but we are probably not capable to make it happen.
Migrating completely to Sphinx and using something like breathe could
be very difficult and it would be a pity to not have super-interlinked
Doxygen documentation (although some say that this feature is not
good).

The negative consequence of using ReST for not is that the quality of
resulting pygrass documentation generated by Doxygen will be bad. I
would ask you (Pietro or Luca) to create some script or doc to
generate the pygrass Sphinx documentation and put it on the GRASS wiki
[1].

If you don't agree or if you have some other ideas, please share.

Vaclav

[1] http://grasswiki.osgeo.org/wiki/Python/pygrass


On 16 January 2013 12:25, Vaclav Petras <wenzeslaus at gmail.com> wrote:
> Hi,
>
> just some brief ideas for now.
>
> Firstly, we have general problem with Doxygen in Python because we use
> non-documented Doxygen feature. Read this doxygen ml thread [1] for
> details.
>
> Secondly, I think that GRASS documentation should use only one
> solution/language. Doxygen supports Doxygen latex-like syntax, HTML
> syntax and Markdown syntax. Unfortunately, it does not support ReST.
>
> On the other hand, ReST is something like standard for Python, so one
> could expect that Doxygen will support it at some point. In this case,
> we can ask (again) on doxygen ml and wait (leave pygrass doc in ReST).
>
> Further comments below.
>
> [1] http://doxygen.10944.n7.nabble.com/Python-docstrings-and-exclamation-mark-td4689.html
>
> On 16 January 2013 10:55, Luca Delucchi <lucadeluge at gmail.com> wrote:
>> Hi all,
>> I'm with Pietro and we are speaking about pygrass documentation.
>> At the moment it is in ReST and it need sphinx to be build. We would
>> like to improve it but we would like to know what is the best solution
>> for it.
>
> For me, there is now best solution now.
>
>> We tough two different solution
>> - kept the actual documentation and add a Makefile where we'll check
>> the presence of sphinx and in that case build the documentation
>
> It would be good to have sphinx documentation for python but than it
> will be only verbatim (current state of art) doc in doxygen generated
> documentation. This is good temporary solution.
>
> There is also some sphinx-doxygen tool [2] to show Doxygen doc in
> sphinx but I haven't tried this tool.
>
>> - move the documentation to doxygen style and html files
>
> What do you mean by HTML files? Do you mean text (non-source code)
> files for Doxygen which allows HTML and Doxygen latex-like syntax?
>
> This option allows to link pygrass documentation with the rest of the
> documentation. This is great advanatage for me.
>>
>> What do you think about this topic?
>>
> I'm not sure, depends mostly on the teoretical support of ReST in Doxygen.
>
> Vaclav
>
> [2] http://michaeljones.github.com/breathe/
>
>
>
>> --
>> 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