[GRASS-dev] sphinx documentation for lib python

[Vaclav Petras]

On Thu, Jun 26, 2014 at 11:50 AM, Sören Gebbert <
soerengebbert at googlemail.com> wrote:

> Hi Luca,
>
> [snip]
> >
> > I take as example raster [0]. For RastRow there is a description with
> > example and after start the documentation about RastRow class.
> > I would like to keep the description with example there and move the
> > RastRow class documentation to the new lib/python documentation. This
> > because I think that http://grass.osgeo.org/grass71/manuals/pygrass/
> > should be for user and the new lib/python documentation is for
> > developers and the two documentations should be separated. Is it more
> > clear now?
>
> IMHO was pygrass designed to be used by Python developers, hence all
> the documentation was written for developers. User usually do not
> write modules with low level map access. :)
> I wouldn't split the pygrass documentation. We need the examples and
> the class documentation to actually program with pygrass. Otherwise
> developers have to search for documentation in two different places.
>
>
Thanks Luca, it is more clear now what you want to do but as Soeren noted
we should make clear who are "users" and who are "developers". I usually
cannot agree with people's opinions here and there, e.g. on Doxygen mailing
list somebody was saying something about commenting Python code in #
comments with Doxygen for developers (probably project developers) and then
using docstrings for users (developers depending on the code/library,
project users). I don't think that these two are separate worlds,
especially in cases (like GRASS) when you time to time end up looking to
the source code itself.

I can agree on having the introduction/tutorial/description of PyGRASS
raster classes in different document (HTML page) than the detailed
documentation of (all) classes, functions and parameters generated from
docstrings. This makes sense to me. However, both these documents (HTML
pages) should be part of the same documentation, Sphinx generated
documentation of python/lib (grass package) in this case.


> However, i do not really understand why the pygrass documentation
> belongs into the manual page section? IMHO all library documentation
> belongs into the programming manual.
>
> If you are speaking about the URL, it is a separate, minor, yet important
problem, I believe. Since we decided to have Python documentation separated
from C documentation we need separate URLs.

We have now this URLs:

http://grass.osgeo.org/documentation/manuals/
http://grass.osgeo.org/manuals/
http://grass.osgeo.org/grass71/manuals/
http://grass.osgeo.org/grass71/manuals/pygrass/
http://grass.osgeo.org/programming7/

And we need to change pygrass to "python/lib" (grass?,
grass-python-package?) and also add wxGUI (wxgui?, grass-wxgui-package).

Here is my draft:

http://grass.osgeo.org/grass71/manuals/programming (for general intro and C
(API?) documentation)
http://grass.osgeo.org/grass71/manuals/python (for grass package)
http://grass.osgeo.org/grass71/manuals/wxgui (for grass wxGUI (not yet?)
package)
http://grass.osgeo.org/grass71/manuals/[index.html] (standard user
documentation)

But we should perhaps consider also possibility of having the same
documentation in two different formats (user in our HTML, Sphinx HTML,
man-like HTML, or perhaps C in Breathe Sphinx, or Python aslo in Doxygen as
we have now). This could be solved by having python-doxygen, python-sphinx
and python as a simlink to one of them (in case of user doc it might be
less straightforward).

Vaclav

See also:
[GRASS-web] Addon manual pages not linked
http://lists.osgeo.org/pipermail/grass-web/2013-December/004587.html

Best regards
> Soeren
>
> >
> >> Thank you,
> >> Vaclav
> >
> > [0] http://grass.osgeo.org/grass71/manuals/pygrass/raster.html
> >
> > --
> > 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/20140626/dd9edf56/attachment.html>