<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Jun 26, 2014 at 11:50 AM, Sören Gebbert <span dir="ltr"><<a href="mailto:soerengebbert@googlemail.com" target="_blank">soerengebbert@googlemail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi Luca,<br>
<br>
[snip]<br>
<div class="">><br>
> I take as example raster [0]. For RastRow there is a description with<br>
> example and after start the documentation about RastRow class.<br>
> I would like to keep the description with example there and move the<br>
> RastRow class documentation to the new lib/python documentation. This<br>
> because I think that <a href="http://grass.osgeo.org/grass71/manuals/pygrass/" target="_blank">http://grass.osgeo.org/grass71/manuals/pygrass/</a><br>
> should be for user and the new lib/python documentation is for<br>
> developers and the two documentations should be separated. Is it more<br>
> clear now?<br>
<br>
</div>IMHO was pygrass designed to be used by Python developers, hence all<br>
the documentation was written for developers. User usually do not<br>
write modules with low level map access. :)<br>
I wouldn't split the pygrass documentation. We need the examples and<br>
the class documentation to actually program with pygrass. Otherwise<br>
developers have to search for documentation in two different places.<br>
<br></blockquote><div><div><br></div><div>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.<br><br></div>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.<br>
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
However, i do not really understand why the pygrass documentation<br>
belongs into the manual page section? IMHO all library documentation<br>
belongs into the programming manual.<br>
<br></blockquote>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.<br><br></div>
<div class="gmail_quote">We have now this URLs:<br></div><div class="gmail_quote"><br><a href="http://grass.osgeo.org/documentation/manuals/">http://grass.osgeo.org/documentation/manuals/</a><br><a href="http://grass.osgeo.org/manuals/">http://grass.osgeo.org/manuals/</a><br>
<a href="http://grass.osgeo.org/grass71/manuals/">http://grass.osgeo.org/grass71/manuals/</a><br><a href="http://grass.osgeo.org/grass71/manuals/pygrass/">http://grass.osgeo.org/grass71/manuals/pygrass/</a><br><a href="http://grass.osgeo.org/programming7/">http://grass.osgeo.org/programming7/</a><br>
<br></div><div class="gmail_quote">And we need to change pygrass to "python/lib" (grass?, grass-python-package?) and also add wxGUI (wxgui?, grass-wxgui-package).<br></div><div class="gmail_quote"><br></div><div class="gmail_quote">
Here is my draft:<br></div><div class="gmail_quote"><br><a href="http://grass.osgeo.org/grass71/manuals/programming">http://grass.osgeo.org/grass71/manuals/programming</a> (for general intro and C (API?) documentation)<br>
<a href="http://grass.osgeo.org/grass71/manuals/python">http://grass.osgeo.org/grass71/manuals/python</a> (for grass package)<br><a href="http://grass.osgeo.org/grass71/manuals/wxgui">http://grass.osgeo.org/grass71/manuals/wxgui</a> (for grass wxGUI (not yet?) package)<br>
<a href="http://grass.osgeo.org/grass71/manuals/[index.html]">http://grass.osgeo.org/grass71/manuals/[index.html]</a> (standard user documentation)<br><br></div><div class="gmail_quote">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).<br>
</div><div class="gmail_quote"><br></div><div class="gmail_quote">Vaclav<br></div><div class="gmail_quote"><br>See also:<br>[GRASS-web] Addon manual pages not linked<br><a href="http://lists.osgeo.org/pipermail/grass-web/2013-December/004587.html">http://lists.osgeo.org/pipermail/grass-web/2013-December/004587.html</a><br>
</div><div class="gmail_quote"><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Best regards<br>
Soeren<br>
<div class="im"><br>
><br>
>> Thank you,<br>
>> Vaclav<br>
><br>
> [0] <a href="http://grass.osgeo.org/grass71/manuals/pygrass/raster.html" target="_blank">http://grass.osgeo.org/grass71/manuals/pygrass/raster.html</a><br>
><br>
> --<br>
> ciao<br>
> Luca<br>
><br>
> <a href="http://gis.cri.fmach.it/delucchi/" target="_blank">http://gis.cri.fmach.it/delucchi/</a><br>
> <a href="http://www.lucadelu.org" target="_blank">www.lucadelu.org</a><br>
</div><div class=""><div class="h5">> _______________________________________________<br>
> grass-dev mailing list<br>
> <a href="mailto:grass-dev@lists.osgeo.org">grass-dev@lists.osgeo.org</a><br>
> <a href="http://lists.osgeo.org/mailman/listinfo/grass-dev" target="_blank">http://lists.osgeo.org/mailman/listinfo/grass-dev</a><br>
</div></div></blockquote></div><br></div></div>