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?
- could I replace doxigen instruction with sphinx instruction in
pygrass docstrings? (for example replace @param with :param)
[0] http://grass.osgeo.org/grass71/manuals/pygrass/index.html
--
ciao
Luca
http://gis.cri.fmach.it/delucchi/
www.lucadelu.org
Hi Luca,
2014-05-27 9:58 GMT+02:00 Luca Delucchi <lucadeluge@gmail.com>:
In the last days some improvements were done on pygrass documentation side [0].
very nice work!
- what do you think about extend sphinx documentation to all python
library of GRASS?
+1
- could I replace doxigen instruction with sphinx instruction in
pygrass docstrings? (for example replace @param with :param)
wouldn't be possible to use syntax which understands both sphinx and doxygen?
Martin
--
Martin Landa * http://geo.fsv.cvut.cz/gwiki/Landa
On 27 May 2014 10:08, Martin Landa <landa.martin@gmail.com> wrote:
Hi Luca,
Hi Martin,
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....
Martin
--
ciao
Luca
http://gis.cri.fmach.it/delucchi/
www.lucadelu.org
Hi Luca,
that's great that you are working on that.
On Tue, May 27, 2014 at 3:58 AM, Luca Delucchi <lucadeluge@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@gmail.com> wrote:
On 27 May 2014 10:08, Martin Landa <landa.martin@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
Lucahttp://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
On 27 May 2014 14:06, Vaclav Petras <wenzeslaus@gmail.com> wrote:
Hi Luca,
Hi Vaclav
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).
I think the same, have documentation for the whole lib/python without
separation of pygrass
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.
I like this proposal, I could finish to work on pygrass documentation
and later start to prepare sphinx for other python library and 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.)
+1
[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.
what do you mean for "conservative design" ?
Vaclav
--
ciao
Luca
http://gis.cri.fmach.it/delucchi/
www.lucadelu.org
On Wed, May 28, 2014 at 2:53 AM, Luca Delucchi <lucadeluge@gmail.com> wrote:
>>
>> [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.
>what do you mean for "conservative design" ?
Probably that there are no distinct (graphically strong) elements:
But it seems that Python documentation goes into the same direction:
https://docs.python.org/2/library/unittest.html >
https://docs.python.org/3/library/unittest.html
I'm not able to contribute anything more exciting and I actually appreciate
a lot that it is the same design as the user manual, so well done, I should
say.
I'm looking forward to separate Python and GUI documentations.
Vaclav
On Tue, May 27, 2014 at 3:58 AM, Luca Delucchi <lucadeluge@gmail.com> wrote:
[0] http://grass.osgeo.org/grass71/manuals/pygrass/index.html
Luca, can you please add the >>> button which is in Python documentation
for the examples with Python command line. I mean a button to convert this:
n = -37
bin(n)
'-0b100101'
n.bit_length()
6
into this:
n = -37
bin(n)
n.bit_length()
https://docs.python.org/2/library/stdtypes.html#long.bit_length
On 30 May 2014 17:20, Vaclav Petras <wenzeslaus@gmail.com> wrote:
On Wed, May 28, 2014 at 2:53 AM, Luca Delucchi <lucadeluge@gmail.com> wrote:
>>
>> [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.
>what do you mean for "conservative design" ?
Probably that there are no distinct (graphically strong) elements:
But it seems that Python documentation goes into the same direction:
https://docs.python.org/2/library/unittest.html >
https://docs.python.org/3/library/unittest.htmlI'm not able to contribute anything more exciting and I actually appreciate
a lot that it is the same design as the user manual, so well done, I should
say.I'm looking forward to separate Python and GUI documentations.
I can work on it next week, if you like the pygrass documentation I
could do the same for Python and GUI
Vaclav
--
ciao
Luca
http://gis.cri.fmach.it/delucchi/
www.lucadelu.org
On Fri, May 30, 2014 at 7:45 PM, Luca Delucchi <lucadeluge@gmail.com> wrote:
On 30 May 2014 17:20, Vaclav Petras <wenzeslaus@gmail.com> wrote:
>
> On Wed, May 28, 2014 at 2:53 AM, Luca Delucchi <lucadeluge@gmail.com>
wrote:
>>
>> >>
>> >> [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.
>> >
>>
>> what do you mean for "conservative design" ?
>
>
> Probably that there are no distinct (graphically strong) elements:
>
>
http://grass.osgeo.org/grass71/manuals/pygrass/raster_elements.html#pygrass.raster.category.Category.set_cats_fmt
>
> But it seems that Python documentation goes into the same direction:
>
> https://docs.python.org/2/library/unittest.html >
> https://docs.python.org/3/library/unittest.html
>
> I'm not able to contribute anything more exciting and I actually
appreciate
> a lot that it is the same design as the user manual, so well done, I
should
> say.
>
> I'm looking forward to separate Python and GUI documentations.
>I can work on it next week, if you like the pygrass documentation I
could do the same for Python and GUIThis would be really great. For Python and GUI I'm always looking to
source code rather than Doxygen but I hope that with Sphinx it will be a
start of a new documentation which I will actually use.
Vaclav
--
ciao
Lucahttp://gis.cri.fmach.it/delucchi/
www.lucadelu.org
On 31 May 2014 02:03, Vaclav Petras <wenzeslaus@gmail.com> wrote:
This would be really great. For Python and GUI I'm always looking to source
code rather than Doxygen but I hope that with Sphinx it will be a start of a
new documentation which I will actually use.
I everybody,
In r60817 I committed Sphinx support for wxgui API doc. To compile the
sphinx documentation you need to launch "make sphinxdoc" and it create
a new directory wxgui in dist/docs/html/.
This is a really first version, and several improvements can be done.
I updated all the docstring containing params and return but there are
a lot of functions and classes without docstrings.
Now I'm going to update Submitting/wxGUI in the trac adding
information how to write docstring
Please report any problems
--
ciao
Luca
http://gis.cri.fmach.it/delucchi/
www.lucadelu.org
Hi Luca,
On Fri, Jun 13, 2014 at 11:59 AM, Luca Delucchi <lucadeluge@gmail.com> wrote:
On 31 May 2014 02:03, Vaclav Petras <wenzeslaus@gmail.com> wrote:
This would be really great. For Python and GUI I'm always looking to source
code rather than Doxygen but I hope that with Sphinx it will be a start of a
new documentation which I will actually use.I everybody,
In r60817 I committed Sphinx support for wxgui API doc. To compile the
sphinx documentation you need to launch "make sphinxdoc" and it create
a new directory wxgui in dist/docs/html/.
Hi Luca,
thanks for the work!
I'm trying to build the docs with: make sphinxdoc , I think the
problem is that on my system the default python interpreter is
python3, so even if I'm launching the make command from inside a
virtualenv using python2 I got this import error:
{{{
$ make sphinxdoc
make -C ./gui/wxpython/docs/wxgui_sphinx/ wxguiclean
make[1]: Entering directory
'/home/pietro/docdat/src/gis/grass71/gui/wxpython/docs/wxgui_sphinx'
rm -rf _build/*
rm -f _templates/layout.html
make[1]: Leaving directory
'/home/pietro/docdat/src/gis/grass71/gui/wxpython/docs/wxgui_sphinx'
make -C ./gui/wxpython/docs/wxgui_sphinx/ wxguiapidoc
make[1]: Entering directory
'/home/pietro/docdat/src/gis/grass71/gui/wxpython/docs/wxgui_sphinx'
GISRC=/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/demolocation/.grassrc71
GISBASE=/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu
PATH="/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/bin:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/bin:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/scripts:$PATH"
PYTHONPATH="/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/etc/python:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/gui/wxpython:$PYTHONPATH"
LD_LIBRARY_PATH="/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/bin:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/scripts:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib::/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib"
LC_ALL=C sphinx-apidoc -T -f -o . ../../
Creating file ./gis_set.rst.
Creating file ./gis_set_error.rst.
Creating file ./menustrings.rst.
Creating file ./wxgui.rst.
Creating file ./animation.rst.
Creating file ./core.rst.
Creating file ./dbmgr.rst.
Creating file ./gcp.rst.
Creating file ./gmodeler.rst.
Creating file ./gui_core.rst.
Creating file ./iclass.rst.
Creating file ./icons.rst.
Creating file ./iscatt.rst.
Creating file ./lmgr.rst.
Creating file ./location_wizard.rst.
Creating file ./mapdisp.rst.
Creating file ./mapswipe.rst.
Creating file ./mapwin.rst.
Creating file ./modules.rst.
Creating file ./nviz.rst.
Creating file ./psmap.rst.
Creating file ./rlisetup.rst.
Creating file ./timeline.rst.
Creating file ./vdigit.rst.
Creating file ./vnet.rst.
Creating file ./web_services.rst.
Creating file ./wxplot.rst.
make[1]: Leaving directory
'/home/pietro/docdat/src/gis/grass71/gui/wxpython/docs/wxgui_sphinx'
make -C ./gui/wxpython/docs/wxgui_sphinx/ wxguihtml
make[1]: Entering directory
'/home/pietro/docdat/src/gis/grass71/gui/wxpython/docs/wxgui_sphinx'
GISRC=/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/demolocation/.grassrc71
GISBASE=/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu
PATH="/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/bin:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/bin:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/scripts:$PATH"
PYTHONPATH="/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/etc/python:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/gui/wxpython:$PYTHONPATH"
LD_LIBRARY_PATH="/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/bin:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/scripts:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib::/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib:/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/lib"
LC_ALL=C sphinx-build -b html -d _build/doctrees .
/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/docs/html/wxgui
Running Sphinx v1.2.2
Exception occurred:
File "/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/etc/python/grass/script/__init__.py",
line 2, in <module>
from db import *
ImportError: No module named 'db'
The full traceback has been saved in /tmp/sphinx-err-xgw_pix0.log, if
you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error
message can be provided next time.
A bug report can be filed in the tracker at
<https://bitbucket.org/birkenfeld/sphinx/issues/>\. Thanks!
Makefile:61: recipe for target 'wxguihtml' failed
make[1]: *** [wxguihtml] Error 1
make[1]: Leaving directory
'/home/pietro/docdat/src/gis/grass71/gui/wxpython/docs/wxgui_sphinx'
include/Make/Sphinx.make:27: recipe for target 'sphinxdoc' failed
make: *** [sphinxdoc] Error 2
}}}
looking at the log file it is clear that I'm using python3 instead of python 2:
{{{
2(py2)ztl ∴ cat /tmp/sphinx-err-xgw_pix0.log
# Sphinx version: 1.2.2
# Python version: 3.4.1
# Docutils version: 0.11 release
# Jinja2 version: 2.7.3
# Loaded extensions:
Traceback (most recent call last):
File "/usr/lib/python3.4/site-packages/sphinx/cmdline.py", line 253, in main
warningiserror, tags, verbosity, parallel)
File "/usr/lib/python3.4/site-packages/sphinx/application.py", line
107, in __init__
confoverrides or {}, self.tags)
File "/usr/lib/python3.4/site-packages/sphinx/config.py", line 229,
in __init__
execfile_(filename, config)
File "/usr/lib/python3.4/site-packages/sphinx/util/pycompat.py",
line 105, in execfile_
exec(code, _globals)
File "conf.py", line 27, in <module>
from grass.script import core
File "/home/pietro/docdat/src/gis/grass71/dist.x86_64-unknown-linux-gnu/etc/python/grass/script/__init__.py",
line 2, in <module>
from db import *
ImportError: No module named 'db'
}}}
I've tried also with:
{{{
$ export PYTHON=/usr/bin/python2
}}}
and then make sphinxdoc, but still it is using the wrong interpreter,
it seems like the make is ignoring my local environment variables,
someone has an idea on how I could try to solve this?
Pietro
On Fri, Jun 13, 2014 at 1:59 PM, Pietro <peter.zamb@gmail.com> wrote:
I'm trying to build the docs with: make sphinxdoc , I think the
problem is that on my system the default python interpreter is
python3
Solved using the follow command:
{{{
$ make SPHINXBUILD=sphinx-build2 sphinxdoc
}}}
But in include/Make/Sphinx.make you already set the SPHINXBUILD
variable to sphin-build2 if available... so why do I need to set the
variable again?
Hi,
I have added "make sphinxdoc" to the weekly cronjob:
http://grass.osgeo.org/grass71/manuals/wxgui/index.html
Nice work, Luca! And of course all wxGUI and Python developers...
Markus