[GRASS-dev] pygrass documentation

[Vaclav Petras]

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