[GRASS-dev] pygrass documentation

lucadelu · January 16, 2013, 9:55am

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.
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
- move the documentation to doxygen style and html files

What do you think about this topic?

--
ciao
Luca

http://gis.cri.fmach.it/delucchi/
www.lucadelu.org

wenzeslaus · January 16, 2013, 11:25am

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@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@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

wenzeslaus · March 1, 2013, 5:50pm

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@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@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@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

neteler · April 26, 2014, 2:58pm

On Fri, Mar 1, 2013 at 6:50 PM, Vaclav Petras <wenzeslaus@gmail.com> wrote:
...

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

That's fine. Martin and me have fixed the sphinx compilation, this now
works on more recent systems:

cd lib/python/pygrass/docs/
make html

It generates the nice Sphinx-based documentation.

---

I have updated the cronjob on grass.osgeo.org accordingly to obtain

http://grass.osgeo.org/programming7/pygrass/

but I struggle on the Debian Wheezy box with this error (maybe bad
sphinx installation there?):

Running Sphinx v1.2b3
loading translations [python]... not available for built-in messages
loading pickled environment... not yet created
building [html]: targets for 6 source files that are out of date
updating environment: 6 added, 0 changed, 0 removed
reading sources... [100%] vector
/home/neteler/grass7_svn_head_progmanual/grass7/lib/python/pygrass/docs/attributes.rst:113:
WARNING: autodoc: failed to import class u'Link' from module
u'pygrass.vector.table'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.2b3-py2.6.egg/sphinx/ext/autodoc.py",
line 335, in import_object
    __import__(self.modname)
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/pygrass/__init__.py",
line 12, in <module>
    from . import errors
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/pygrass/errors.py",
line 8, in <module>
    from grass.pygrass.messages import get_msgr
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/pygrass/__init__.py",
line 13, in <module>
    from . import gis
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/pygrass/gis/__init__.py",
line 23, in <module>
    script.gisenv()
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/script/core.py",
line 979, in gisenv
    s = read_command("g.gisenv", flags='n')
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/script/core.py",
line 420, in read_command
    ps = pipe_command(*args, **kwargs)
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/script/core.py",
line 395, in pipe_command
    return start_command(*args, **kwargs)
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/script/core.py",
line 354, in start_command
    return Popen(args, **popts)
  File "/home/neteler/grass7_svn_head_progmanual/grass7/dist.x86_64-unknown-linux-gnu/etc/python/grass/script/core.py",
line 64, in __init__
    startupinfo, creationflags)
  File "/usr/lib/python2.6/subprocess.py", line 623, in __init__
    errread, errwrite)
  File "/usr/lib/python2.6/subprocess.py", line 1141, in _execute_child
    raise child_exception
OSError: [Errno 2] No such file or directory

Any ideas? On my Fedora 20 it works nicely.

thanks
Markus

neteler · April 27, 2014, 9:35pm

(back to list)

On Sun, Apr 27, 2014 at 11:18 PM, Vaclav Petras <wenzeslaus@gmail.com> wrote:

On Sun, Apr 27, 2014 at 4:57 PM, Markus Neteler <neteler@osgeo.org> wrote:

it works on my Fedora 20 box.
Just Debian does not behave.

> Are you sure you are in a GRASS session?

Sure, thanks to
https://trac.osgeo.org/grass/changeset/59947

In this case, it is possible that the problem is the same as the one with
toolboxes and few other things, the session might not be properly
established. Have you tried be in GRASS and then do make? This helps in the
case of toolboxes on Mac.

Indeed, inside a GRASS session it also works on the Debian server (not
needed on Fedora thanks to r59947).

So the bug must be somewhere in
include/Make/Rules.make
--> run_grass

Likely some silly path issue.

Markus

neteler · April 28, 2014, 5:39am

... Sphinx issue solved on server (it was an issue in the cronjob
script). Now available:

The PyGRASS manual (Sphinx based), updated weekly:
http://grass.osgeo.org/programming7/pygrass/

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 )

Markus

lucadelu · April 28, 2014, 6:15am

On 28 April 2014 07:39, Markus Neteler <neteler@osgeo.org> wrote:

... Sphinx issue solved on server (it was an issue in the cronjob
script). Now available:

The PyGRASS manual (Sphinx based), updated weekly:
http://grass.osgeo.org/programming7/pygrass/

Thanks,

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!

Markus

--
ciao
Luca

http://gis.cri.fmach.it/delucchi/
www.lucadelu.org

wenzeslaus · April 28, 2014, 12:57pm

On Mon, Apr 28, 2014 at 1:39 AM, Markus Neteler <neteler@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

Pietro2 · April 28, 2014, 1:02pm

Hi Markus and Martin,

sorry for the late reply but I'm without connection on these days...

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

... Sphinx issue solved on server (it was an issue in the cronjob
script). Now available:

The PyGRASS manual (Sphinx based), updated weekly:
http://grass.osgeo.org/programming7/pygrass/

Thank you for your great work on the pygrass documentation!

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 )

yes, I think would be much clearer...

Pietro

Pietro2 · April 28, 2014, 1:23pm

On Mon, Apr 28, 2014 at 2:57 PM, Vaclav Petras <wenzeslaus@gmail.com> wrote:

[cut] 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.

Sphinx has support for python/C/C++/javascript [0].
May be we could reconsider [1] to move everything under sphinx.

But I'm not sure it is feasible.

Best regards

Pietro

[0] http://sphinx-doc.org/domains.html
[1] https://trac.osgeo.org/grass/ticket/151

wenzeslaus · April 28, 2014, 1:34pm

On Mon, Apr 28, 2014 at 9:23 AM, Pietro <peter.zamb@gmail.com> wrote:

On Mon, Apr 28, 2014 at 2:57 PM, Vaclav Petras <wenzeslaus@gmail.com>
wrote:
> [cut] 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.

Sphinx has support for python/C/C++/javascript [0].
May be we could reconsider [1] to move everything under sphinx.

But I'm not sure it is feasible.

Doxygen has support for Python too, but it is not good enough, I would

guess that it is the same for C in Sphinx. The only thing which could
change this is Breathe [2]. More investigation is needed in this case (as
well as in replacement? of HTML manual with Sphinx).

[0] http://sphinx-doc.org/domains.html
[1] https://trac.osgeo.org/grass/ticket/151

[2] http://michaeljones.github.io/breathe/