Re: [GRASS-dev] sphinx documentation for lib python
Hi,
recent changes broke the sphinx manual creation on grass.osgeo.org:
# Sphinx version: 1.2b3
# Python version: 2.6.6
# Docutils version: 0.8.1 release
# Jinja2 version: 2.6
# Loaded extensions:
Traceback (most recent call last):
File
/usr/local/lib/python2.6/dist-packages/Sphinx-1.2b3-py2.6.egg/sphinx/cmdline.py,
line 245, in main
warningiserror, tags, verbosity, parallel)
File
/usr/local/lib/python2.6/dist-packages/Sphinx-1.2b3-py2.6.egg/sphinx/application.py,
line 107, in __init__
confoverrides or {}, self.tags)
File
/usr/local/lib/python2.6/dist-packages/Sphinx-1.2b3-py2.6.egg/sphinx/config.py,
line 229, in __init__
execfile_(filename, config)
File
/usr/local/lib/python2.6/dist-packages/Sphinx-1.2b3-py2.6.egg/sphinx/util/pycompat.py,
line 93, in execfile_
exec code in _globals
File conf.py, line 27, in module
from grass.script import core
ImportError: No module named grass.script
Any ideas why this no longer works? The cronjob is essentially
untouched here as is the Debian box.
Markus
___
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
On 3 July 2014 17:08, Martin Landa landa.mar...@gmail.com wrote: Hi, HI, 2014-07-03 17:06 GMT+02:00 Martin Landa landa.mar...@gmail.com: sphinxdoc' please consider renaming this rule to `sphinxdocs` (similarly to `htmldocs` and friends - see include/Make/Docs.make). Martin ok, do you think it is better to have lib/python and gui/wxpython in the same Make rule or do you prefer two different? -- ciao Luca http://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
Re: [GRASS-dev] sphinx documentation for lib python
Hi, 2014-07-04 8:50 GMT+02:00 Luca Delucchi lucadel...@gmail.com: ok, do you think it is better to have lib/python and gui/wxpython in the same Make rule or do you prefer two different? I have no strong opinion, one rule (`sphinxdocs`) seems to be enough for me. Martin -- Martin Landa * http://geo.fsv.cvut.cz/gwiki/Landa ___ grass-dev mailing list grass-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
On 3 July 2014 17:08, Martin Landa landa.mar...@gmail.com wrote: Hi, Hi again please consider renaming this rule to `sphinxdocs` (similarly to `htmldocs` and friends - see include/Make/Docs.make). Martin I saw that the name in the main Makefile are something like htmldocs and htmldox, maybe we should rename it to htmlsphinx, mansphinx and maybe add htmlsphinx-single and latexsphinx? -- ciao Luca http://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
Re: [GRASS-dev] sphinx documentation for lib python
Hi devs, I just commit (r61141) the first step of Python Sphinx documentation. Now it compile with WXGUI Sphinx documentation so just launching 'make sphinxdoc' I removed pygrass/docs and kept the useful pages in the new lib/python/docs/ Please test it and report any problems. Next steps is to update the docstring in the python files. I already started with lib/python/imaging/ -- ciao Luca http://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
Re: [GRASS-dev] sphinx documentation for lib python
Hi, 2014-07-03 17:02 GMT+02:00 Luca Delucchi lucadel...@gmail.com: I just commit (r61141) the first step of Python Sphinx documentation. Now it compile with WXGUI Sphinx documentation so just launching 'make sphinxdoc' I removed pygrass/docs and kept the useful pages in the new lib/python/docs/ thanks for this work, I like to see that sphinx is not called from main rule (`make`). Martin -- Martin Landa * http://geo.fsv.cvut.cz/gwiki/Landa ___ grass-dev mailing list grass-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
Hi, 2014-07-03 17:06 GMT+02:00 Martin Landa landa.mar...@gmail.com: sphinxdoc' please consider renaming this rule to `sphinxdocs` (similarly to `htmldocs` and friends - see include/Make/Docs.make). Martin -- Martin Landa * http://geo.fsv.cvut.cz/gwiki/Landa ___ grass-dev mailing list grass-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
On 26 June 2014 18:43, Vaclav Petras wenzesl...@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 ___ grass-dev mailing list grass-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
Hi Luca, On Thu, Jun 26, 2014 at 11:02 AM, Luca Delucchi lucadel...@gmail.com wrote: Hi devs, I'm going to start to work on sphinx documentation for lib/python in the next week/s. I would like to know which directory do you like to have on the docs. I think that all the directories (ctypes, imaging, pydispatch, pygrass, script, temporal) should be in. I'm not sure about how it works with ctypes but all the other should be there for sure, although pydispatch and imaging are little bit special since they partially contain 3rd party code. what do you think? PS I would like also to modify pygrass documentation removing all method, classes and function documentation (moving it to the new programming documentation) and leaving it only the user documentation with example. is it ok for you? I'm not exactly sure what do you mean by that. I know that there are different possibilities how to approach this. Can please you provide more examples and describe it more (e.g. draft the rules how doc should be written)? Thank you, Vaclav -- ciao Luca http://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 ___ grass-dev mailing list grass-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
On 26 June 2014 17:21, Vaclav Petras wenzesl...@gmail.com wrote: Hi Luca, Hi Vaclav, On Thu, Jun 26, 2014 at 11:02 AM, Luca Delucchi lucadel...@gmail.com wrote: Hi devs, I'm going to start to work on sphinx documentation for lib/python in the next week/s. I would like to know which directory do you like to have on the docs. I think that all the directories (ctypes, imaging, pydispatch, pygrass, script, temporal) should be in. I'm not sure about how it works with ctypes but all the other should be there for sure, although pydispatch and imaging are little bit special since they partially contain 3rd party code. Yes, after sent the email I had your same doubt with ctypes. I'll try and see what happen :-) what do you think? PS I would like also to modify pygrass documentation removing all method, classes and function documentation (moving it to the new programming documentation) and leaving it only the user documentation with example. is it ok for you? I'm not exactly sure what do you mean by that. I know that there are different possibilities how to approach this. Can please you provide more examples and describe it more (e.g. draft the rules how doc should be written)? 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? 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@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
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. 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. 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@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev ___ grass-dev mailing list grass-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
Re: [GRASS-dev] sphinx documentation for lib python
On Thu, Jun 26, 2014 at 11:50 AM, Sören Gebbert soerengebb...@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@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev ___ grass-dev mailing list grass-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/grass-dev
