[GRASS-dev] sphinx documentation for lib python

[Luca Delucchi]

On 26 June 2014 18:43, Vaclav Petras <wenzeslaus at gmail.com> wrote:
>
>
> 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.
>

Ok, so same documentation but different pages, it make sense for me

>>
>> 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)
>

I like your proposal and it make sense for me.
Maybe we could create something like

http://grass.osgeo.org/grass71/manuals/user (standard user documentation)
http://grass.osgeo.org/grass71/manuals/devs (and inside the link to
programming, python, wxgui using an index page like the index of 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).
>

Sorry it is not really clear for me but I support the idea to have the
same documentation in two different formats (specially for the Python
side, using as maintained the Sphinx version and as supported the
doxygen version)

> Vaclav
>


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


I would like to add link in the main index.html under General or
Miscellaneous & Variables cell, but I discovered that we have not
http://grass.osgeo.org/grass71/manuals/addons/; Martin are you able to
do this, after that I could add the link to the manual....

-- 
ciao
Luca

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