On Thu, Jun 26, 2014 at 11:50 AM, Sören Gebbert < [email protected]> 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 > > [email protected] > > http://lists.osgeo.org/mailman/listinfo/grass-dev >
_______________________________________________ grass-dev mailing list [email protected] http://lists.osgeo.org/mailman/listinfo/grass-dev
