python documentation: start sphinx documentation for lib/python

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@61141 15284696-431f-4ddb-bdfa-cd5b030d7da7

include/Make/Sphinx.make

@@ -18,11 +18,17 @@ checksphinx:
 
 cleansphinx:
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiclean
+	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs libpythonclean
 
 sphinxdoc: checksphinx cleansphinx
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiapidoc
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguihtml
+	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
+	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonhtml
 
 sphinxman:checksphinx cleansphinx
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiapidoc
 	$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiman
+	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
+	$(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonman
+

lib/python/pygrass/docs/Makefile

@@ -1,6 +1,6 @@
 # Makefile for Sphinx documentation
 #
-MODULE_TOPDIR=../../../..
+MODULE_TOPDIR=../../..
 include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 
@@ -14,14 +14,14 @@ SPHINXBUILD   = sphinx-build
 endif
 PAPER         =
 BUILDDIR      = _build
-BUILDDIR_HTML = $(HTMLDIR)/pygrass
+BUILDDIR_HTML = $(HTMLDIR)/libpython
 
 MYGISBASE = $(GISBASE)
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . src/
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -29,60 +29,74 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .DEFAULT_GOAL := help
 
-help:
+libpythonhelp:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  man        to make manual pages"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  libpythonhtml       to make standalone HTML files"
+	@echo "  libpythondirhtml    to make HTML files named index.html in directories"
+	@echo "  libpythonsinglehtml to make a single large HTML file"
+	@echo "  libpythonepub       to make an epub"
+	@echo "  libpythonlatex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  libpythonlatexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  libpythonman        to make manual pages"
+	@echo "  libpythondoctest    to run all doctests embedded in the documentation (if enabled)"
 
-clean:
+libpythonclean:
 	-rm -rf $(BUILDDIR)/*
 	-rm -f _templates/layout.html
+	-rm -f src/ctypes*.rst
+	-rm -f src/imaging.rst
+	-rm -f src/pydispatch.rst
+	-rm -f src/pygrass.*rst
+	-rm -f src/script.rst
+	-rm -f src/temporal.rst
 
-html:
+libpythonapidoc:
+#	$(call run_grass, sphinx-apidoc -T -f -o src/ ../ctypes/)
+	$(call run_grass,sphinx-apidoc -T -f -o src/ ../imaging/)
+	$(call run_grass,sphinx-apidoc -T -f -o src/ ../pydispatch/)
+	$(call run_grass,sphinx-apidoc -T -f -o src/ ../pygrass/)
+	$(call run_grass,sphinx-apidoc -T -f -o src/ ../script/)
+	$(call run_grass,sphinx-apidoc -T -f -o src/ ../temporal/)
+	
+libpythonhtml:
 	$(call run_grass,$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
 
-dirhtml:
+libpythondirhtml:
 	$(call run_grass,$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
 
-singlehtml:
+libpythonsinglehtml:
 	$(call run_grass,$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR_HTML)"
 
-epub:
+libpythonepub:
 	$(call run_grass,$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub)
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/"
 
-latex:
+libpythonlatex:
 	$(call run_grass,$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex)
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf:
+libpythonlatexpdf:
 	$(call run_grass,$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex)
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/"
 
-man:
+libpythonman:
 	$(call run_grass,$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(MANDIR))
 	@echo
 	@echo "Build finished. The manual pages are in $(MANDIR)/"
 
-doctest:
+libpythondoctest:
 	$(call run_grass,$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest)
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."

lib/python/pygrass/docs/_templates/layout.html.template

@@ -4,6 +4,6 @@
 {% endblock %}
 
 {% block header %}
-<img src="../grass_logo.png" alt="GRASS logo">
+<img src="../grass_logo.png" alt="GRASS GIS logo">
 <hr class="header">
 {% endblock %}

lib/python/docs/_templates/oholosidebar.html

@@ -0,0 +1,9 @@
+<p width="210px">
+<iframe src='http://www.ohloh.net/p/3666/widgets/project_factoids_stats.html' scrolling='no' marginHeight=0 marginWidth=0 style='height: 160px; width: 210px; border: none;'></iframe>
+</p>
+<p width="210px">
+<iframe src='http://www.ohloh.net/p/3666/widgets/project_languages.html' scrolling='no' marginHeight=0 marginWidth=0 style='height: 160px; width: 210px; border: none;'></iframe>
+</p>
+<p width="210px">
+<iframe src='http://www.ohloh.net/p/3666/widgets/project_cocomo.html' scrolling='no' marginHeight=0 marginWidth=0 style='height: 160px; width: 210px; border: none;'></iframe>
+</p>

lib/python/pygrass/docs/conf.py

@@ -1,9 +1,10 @@
 # -*- coding: utf-8 -*-
 #
-# PyGRASS documentation build configuration file, created by
-# sphinx-quickstart2 on Sat Jun 16 18:53:32 2012.
+# wxGUI documentation build configuration file, created by
+# sphinx-quickstart on Tue Jun  3 09:20:51 2014.
 #
-# This file is execfile()d with the current directory set to its containing dir.
+# This file is execfile()d with the current directory set to its
+# containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
@@ -22,6 +23,12 @@ from shutil import copy
 if not os.getenv('GISBASE'):
     sys.exit("GISBASE not defined")
 sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'ctypes')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'imaging')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'pydispatch')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'pygrass')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'script')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'temporal')))
 
 from grass.script import core
 
@@ -46,9 +53,18 @@ with open("_templates/layout.html", "a+b") as f:
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -63,17 +79,17 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'PyGRASS'
-copyright = u'2012-2014, Pietro Zambelli'
+project = u'Python library documentation'
+copyright = u'2014, GRASS Development Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-#version = '0.2'
+#version = '0.1'
 # The full version, including alpha/beta/rc tags.
-#release = 'beta'
+#release = '0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -89,7 +105,8 @@ language = 'python'
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
-# The reST default role (used for this markup: `text`) to use for all documents.
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -109,15 +126,11 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
-# If true, doctest flags (comments looking like # doctest: FLAG, ...)
-# at the ends of lines and <BLANKLINE> markers are removed for all code blocks
-# showing interactive Python sessions (i.e. doctests). Default is true.
-trim_doctest_flags = True
-
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
 
-intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
 
-# -- Options for HTML output ---------------------------------------------------
+# -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -152,6 +165,11 @@ html_theme = 'traditional'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
@@ -194,10 +212,10 @@ html_show_copyright = True
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'PyGrassdoc'
+htmlhelp_basename = 'PythonLibdoc'
 
 
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
@@ -211,10 +229,11 @@ latex_elements = {
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', 'PyGrass.tex', u'PyGRASS Documentation',
-   u'Pietro Zambelli', 'manual'),
+  ('index', 'PythonLib.tex', u'Python Librart Documentation',
+   u'GRASS Development Team', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -238,27 +257,27 @@ latex_documents = [
 #latex_domain_indices = True
 
 
-# -- Options for manual page output --------------------------------------------
+# -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'pygrass', u'PyGRASS Documentation',
-     [u'Pietro Zambelli'], 1)
+    ('index', 'PythonLib', u'Python Library Documentation',
+     [u'GRASS Development Team'], 1)
 ]
 
 # If true, show URL addresses after external links.
 #man_show_urls = False
 
 
-# -- Options for Texinfo output ------------------------------------------------
+# -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'PyGRASS', u'PyGRASS Documentation',
-   u'Pietro Zambelli', 'PyGRASS', 'One line description of project.',
+  ('index', 'PythonLib', u'Python Library Documentation',
+   u'GRASS Development Team', 'PythonLib', 'One line description of project.',
    'Miscellaneous'),
 ]
 
@@ -271,14 +290,26 @@ texinfo_documents = [
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
 
-# -- Options for Epub output ---------------------------------------------------
+# -- Options for Epub output ----------------------------------------------
 
 # Bibliographic Dublin Core info.
-epub_title = u'PyGRASS'
-epub_author = u'Pietro Zambelli'
-epub_publisher = u'Pietro Zambelli'
-epub_copyright = u'2012, Pietro Zambelli'
+epub_title = u'PythonLib'
+epub_author = u'GRASS Development Team'
+epub_publisher = u'GRASS Development Team'
+epub_copyright = u'2014, GRASS Development Team'
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = u'wxGUI'
+
+# The HTML theme for the epub output. Since the default themes are not optimized
+# for small screen space, using the same theme for HTML and epub output is
+# usually not wise. This defaults to 'epub', a theme designed to save visual
+# space.
+#epub_theme = 'epub'
 
 # The language of the text. It defaults to the language option
 # or en if the language is not set.
@@ -297,6 +328,9 @@ epub_copyright = u'2012, Pietro Zambelli'
 # A tuple containing the cover image and cover page html template filenames.
 #epub_cover = ()
 
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
 # HTML files that should be inserted before the pages created by sphinx.
 # The format is a list of tuples containing the path and title.
 #epub_pre_files = []
@@ -306,10 +340,25 @@ epub_copyright = u'2012, Pietro Zambelli'
 #epub_post_files = []
 
 # A list of files that should not be packed into the epub file.
-#epub_exclude_files = []
+epub_exclude_files = ['search.html']
 
 # The depth of the table of contents in toc.ncx.
 #epub_tocdepth = 3
 
 # Allow duplicate toc entries.
 #epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the PIL.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True

lib/python/pygrass/docs/make.bat

@@ -3,7 +3,7 @@
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build2
+	set SPHINXBUILD=sphinx-build
 )
 set BUILDDIR=_build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
@@ -33,6 +33,8 @@ if "%1" == "help" (
 	echo.  texinfo    to make Texinfo files
 	echo.  gettext    to make PO message catalogs
 	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
 	echo.  linkcheck  to check all external links for integrity
 	echo.  doctest    to run all doctests embedded in the documentation if enabled
 	goto end
@@ -44,6 +46,20 @@ if "%1" == "clean" (
 	goto end
 )
 
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
 if "%1" == "html" (
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 	if errorlevel 1 exit /b 1
@@ -99,9 +115,9 @@ if "%1" == "qthelp" (
 	echo.
 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
 .qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PyGrass.qhcp
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\wxGUI.qhcp
 	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PyGrass.ghc
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\wxGUI.ghc
 	goto end
 )
 
@@ -129,6 +145,26 @@ if "%1" == "latex" (
 	goto end
 )
 
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
 if "%1" == "text" (
 	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
 	if errorlevel 1 exit /b 1
@@ -187,4 +223,20 @@ results in %BUILDDIR%/doctest/output.txt.
 	goto end
 )
 
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
 :end

lib/python/docs/src/index.rst

@@ -0,0 +1,14 @@
+GRASS GIS Python library documentation
+==========================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   script
+   pygrass_index
+   temporal
+   imaging
+   pydispatch
+

lib/python/pygrass/docs/gis.rst

@@ -6,17 +6,6 @@ GRASS database management
 These classes are used to manage the infrastructure
 of GRASS database: Gisdbase, Location and Mapset
 
-.. autoclass:: pygrass.gis.Gisdbase
-    :members:
-
-.. autoclass:: pygrass.gis.Location
-    :members:
-
-.. autoclass:: pygrass.gis.Mapset
-    :members:
-
-.. autoclass:: pygrass.gis.VisibleMapset
-    :members:
 
 .. _Region-label:
 
@@ -26,5 +15,3 @@ Region management
 The Region class it is useful to obtain information
 about the computational region and to change it.
 
-.. autoclass:: pygrass.gis.region.Region
-    :members:

lib/python/docs/src/pygrass_index.rst

@@ -0,0 +1,57 @@
+PyGRASS documentation
+===================================
+
+Python is a programming language which is more powerful than shell
+scripting but easier and more forgiving than C. ``PyGRASS`` is an
+object-oriented Python Application Programming Interface (API) for
+GRASS GIS. ``PyGRASS`` offers interfaces to GRASS modules and
+functionality, as well as to vector and raster data. For details,
+see Zambelli et al. (2013) in the references below. ``PyGRASS``
+improves the integration between GRASS GIS and Python, making the
+use of Python under GRASS more consistent with the language itself.
+Furthermore, it simplifies GRASS scripting and programming and more
+natural for the user.
+
+Background: In 2006, GRASS GIS developers started to adopt Python
+for the new GUI. Due to this Python became more and more important
+and developers converted all shell scripts from GRASS GIS 6 to Python
+for GRASS GIS 7.
+
+To work with ``PyGRASS`` you need an up-to-date version of GRASS
+GIS 7. The only action before starting to work with ``PyGRASS`` is
+to launch GRASS GIS 7 and from the console launch ``python`` or
+``ipython`` (the second one is the recommended way).
+
+
+Read more about how to work with ``pygrass`` in this documentation.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   pygrass_gis
+   pygrass_raster
+   pygrass_vector
+   pygrass_modules
+   pygrass_messages
+   pygrass
+
+
+References
+^^^^^^^^^^^^^
+
+* Zambelli P, Gebbert S, Ciolli M., 2013. *Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS)*. ISPRS International Journal of Geo-Information. 2(1):201-219. `doi:10.3390/ijgi2010201 <http://dx.doi.org/10.3390/ijgi2010201>`_
+* `Python related articles in the GRASS GIS Wiki <http://grasswiki.osgeo.org/wiki/Category:Python>`_
+
+This project has been funded with support from the `Google Summer of Code 2012 <http://trac.osgeo.org/grass/wiki/GSoC#PythonhighlevelmapinteractionforGRASSGIS>`_
+
+
+..
+    Indices and tables
+    ==================
+
+    * :ref:`genindex`
+    * :ref:`modindex`
+    * :ref:`search`
+

lib/python/pygrass/docs/messages.rst

@@ -4,12 +4,3 @@ PyGRASS message interface
 The PyGRASS message interface is a fast and exit-safe
 interface to the `GRASS C-library message functions <http://grass.osgeo.org/programming7/gis_2error_8c.html>`_.
 
-.. autoclass:: pygrass.messages.Messenger
-    :members:
-
-.. autoclass:: pygrass.messages.FatalError
-    :members:
-
-.. autofunction:: pygrass.messages.message_server
-
-.. autofunction:: pygrass.messages.get_msgr

lib/python/pygrass/docs/raster.rst

@@ -116,8 +116,6 @@ time you are writing a new map, the row is add to the file as the last row. ::
     >>> new.exist()
     False
 
-.. autoclass:: pygrass.raster.RasterRow
-    :members:
 
 .. _RasterRowIO-label:
 
@@ -141,8 +139,6 @@ for reading and use the default row write access as in the RasterRow class. ::
     [ 144.99488831  145.22894287  145.57142639]
     >>> elev.close()
 
-.. autoclass:: pygrass.raster.RasterRowIO
-    :members:
 
 .. _RasterSegment-label:
 
@@ -211,8 +207,6 @@ to write a single value to the map. ::
     >>> elev.close()
     >>> elev.remove()
 
-.. autoclass:: pygrass.raster.RasterSegment
-    :members:
 
 .. _RasterNumpy-label:
 
@@ -252,9 +246,6 @@ to load all the map in memory. ::
     True
     >>> el.remove()
 
-.. autoclass:: pygrass.raster.RasterNumpy
-    :members:
-
 
 .. _Raster library: http://grass.osgeo.org/programming7/rasterlib.html
 .. _RowIO library: http://grass.osgeo.org/programming7/rowiolib.html

lib/python/pygrass/docs/vector.rst

@@ -116,17 +116,3 @@ Now, find an area with an island inside... ::
     >>> isle = area.isles[0]
     >>> isle.bbox()
     Bbox(199947.296494, 199280.969494, 754920.623987, 754351.812986)
-
-
-
-Vector
-----------
-
-.. autoclass:: pygrass.vector.Vector
-    :members:
-
-VectorTopo
-----------
-
-.. autoclass:: pygrass.vector.VectorTopo
-    :members:

lib/python/pygrass/docs/intro.rst

@@ -1,14 +0,0 @@
-Introduction
-=============
-
-To work with ``pygrass`` you need an up-to-date version of GRASS GIS 7.
-You can obtain a recent version following the information provided on the
-`main Web site <http://grass.osgeo.org/download/software/>`_
-of GRASS, and you can read more about compilation in the 
-`GRASS GIS Wiki <http://grasswiki.osgeo.org/wiki/Compile_and_Install>`_
-
-The only action before starting to work with ``pygrass`` is to launch 
-GRASS GIS 7 and from the console launch ``python`` or ``ipython`` 
-(the second one is the recommended way).
-
-Read more about how to work with ``pygrass`` in this documentation.

lib/python/pygrass/docs/modules_grid.rst

@@ -1,25 +0,0 @@
-GridModule for raster multiprocessing
-=====================================
-
-The GridModule class permits to work with raster data and all the 
-processor cores of your computer. It divides the input data into the 
-number of choosen rows and columns and after it patches the results 
-together to obtain only one output map.
-
-.. automodule:: pygrass.modules.grid.grid
-    :members:
-
-Functions
-------------
-
-Split
-^^^^^^^^
-
-.. automodule:: pygrass.modules.grid.split
-    :members:
-
-Patch
-^^^^^^^^
-
-.. automodule:: pygrass.modules.grid.patch
-    :members:

lib/python/pygrass/docs/raster_elements.rst

@@ -1,136 +0,0 @@
-Raster elements
-=================
-
-.. _RasterCategory-label:
-
-Categories
-----------
-
-All the raster classes support raster categories and share commons methods
-to modify the raster category.
-It is possible to check if the map has or not the categories with the
-``has_cats`` method. ::
-
-    >>> elev.has_cats()
-    False
-
-Opening a map that has category, for example the "landcove_1m" raster map
-from the North Carolina mapset. The ``has_cats`` method return True. ::
-
-    >>> land = raster.RasterRow('landcover_1m')
-    >>> land.has_cats()
-    True
-
-Get and set the categories title, with: ::
-
-    >>> land.cats_title
-    'Rural area: Landcover'
-    >>> land.cats_title = 'Rural area: Landcover2'
-    >>> land.cats_title
-    'Rural area: Landcover2'
-    >>> land.cats_title = 'Rural area: Landcover'
-
-Get the number of categories of the map with: ::
-
-    >>> land.num_cats()
-    11
-
-See all the categories with: ::
-
-    >>> land.cats
-    [('pond', 1, None),
-     ('forest', 2, None),
-     ('developed', 3, None),
-     ('bare', 4, None),
-     ('paved road', 5, None),
-     ('dirt road', 6, None),
-     ('vineyard', 7, None),
-     ('agriculture', 8, None),
-     ('wetland', 9, None),
-     ('bare ground path', 10, None),
-     ('grass', 11, None)]
-
-Access a single category, using Rast_get_ith_cat(), with: ::
-
-    >>> land.cats[0]
-    ('pond', 1, None)
-    >>> land.cats['pond']
-    ('pond', 1, None)
-    >>> land.get_cat(0)
-    ('pond', 1, None)
-    >>> land.get_cat('pond')
-    ('pond', 1, None)
-
-Add new or change existing categories: ::
-
-    >>> land.set_cat('label', 1)
-    >>> land.get_cat('label')
-    ('label', 1, None)
-    >>> land.set_cat('pond', 1, 1)
-
-
-Sort categories, with: ::
-
-    >>> land.sort_cats()
-
-
-Copy categories from another raster map with: ::
-
-    >>> land.copy_cats(elev)
-
-Read and Write: ::
-
-    >>> land.read_cats()
-    >>> #land.write_cats()
-
-Get a Category object or set from a Category object: ::
-
-    >>> cats = land.get_cats()
-    >>> land.set_cats(cats)
-
-Export and import from a file: ::
-
-    >>> land.write_cats_rules('land_rules.csv', ';')
-    >>> land.read_cats_rules('land_rules.csv', ';')
-
-.. autoclass:: pygrass.raster.category.Category
-    :members:
-
-.. _Buffer-label:
-
-Buffer
-------
-
-The buffer class is used to interact with a memory buffer of a map like a
-raster row. The buffer class is based on the `numpy.ndarray`_ class. Therefore
-all the nice feature of the ndarray are allowed.
-
-.. autoclass:: pygrass.raster.buffer.Buffer
-    :members:
-
-.. _numpy.ndarray: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
-
-
-.. _RowIO-label:
-
-RowIO
-------
-
-.. autoclass:: pygrass.raster.rowio.RowIO
-    :members:
-
-.. _Segment-label:
-
-Segment
--------
-
-.. autoclass:: pygrass.raster.segment.Segment
-    :members:
-
-.. _History-label:
-
-History
---------
-
-.. autoclass:: pygrass.raster.history.History
-    :members:

lib/python/pygrass/docs/vector_attributes.rst

@@ -1,144 +0,0 @@
-Vector Attributes
-===================
-
-It is possible to access the vector attributes with: ::
-
-    >>> from pygrass.vector import Vector
-    >>> municip = Vector('boundary_municp_sqlite')
-    >>> municip.open()
-    >>> municip.dblinks
-    DBlinks([[Link(1, boundary_municp, sqlite)]])
-
-The vector map have a ``table`` attributes that contain a Table object, that
-have some useful attributes like: layer, name, driver, etc.
-
-    >>> link = municip.dblinks[1]
-    >>> link.number
-    1
-    >>> link.name
-    'boundary_municp'
-    >>> link.table_name
-    'boundary_municp_sqlite'
-    >>> link.driver
-    'sqlite'
-    >>> link.database                                     # doctest: +ELLIPSIS
-    '.../sqlite.db'
-    >>> link.key
-    'cat'
-
-It is possible to change values, like: ::
-
-    >>> link.name = 'boundary'
-    >>> link.driver = 'pg'
-    >>> link.database = 'host=localhost,dbname=grassdb'
-    >>> link.key = 'gid'
-
-Now change again to old values: ::
-
-    >>> link.name = 'boundary_municp_sqlite'
-    >>> link.driver = 'sqlite'
-    >>> link.database = '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite.db'
-    >>> link.key = 'cat'
-
-Link object have methods that return a
-:ref:`Connection object <python:library:sqlite3:connection-objects>`, and to
-return a Table object: ::
-
-    >>> conn = link.connection()
-    >>> cur = conn.cursor()
-    >>> import sql
-    >>> cur.execute(sql.SELECT.format(cols=', '.join(['cat', 'AREA']),
-    ...                               tname=link.name))   # doctest: +ELLIPSIS
-    <sqlite3.Cursor object at ...>
-    >>> cur.fetchone()
-    (1, 0.0)
-    >>> cur.close()
-    >>> conn.close()
-
-From the Link object we can instantiate a Table object that allow user to
-make simple query with the Filters object: ::
-
-    >>> table = link.table()
-    >>> table.filters.select('cat', 'COUNTY',
-    ...                      'AREA','PERIMETER').order_by('AREA').limit(3)
-    Filters('SELECT cat, COUNTY, AREA, PERIMETER FROM boundary_municp_sqlite ORDER BY AREA LIMIT 3;')
-    >>> cur = table.execute()
-    >>> for row in cur.fetchall():
-    ...     print repr(row)
-    ...
-    (1, u'SURRY', 0.0, 1415.331)
-    (2, u'SURRY', 0.0, 48286.011)
-    (3, u'CASWELL', 0.0, 5750.087)
-
-
-Then we can get table information about table columns, from the columns
-attribute that is an instantiation of a Columns class.
-
-
-    >>> table.columns                                     # doctest: +ELLIPSIS
-    Columns([(u'cat', u'integer'), ..., (u'ACRES', u'double precision')])
-    >>> table.columns.names()                             # doctest: +ELLIPSIS
-    [u'cat', u'OBJECTID', u'AREA', u'PERIMETER', ..., u'ACRES']
-    >>> table.columns.types()                             # doctest: +ELLIPSIS
-    [u'integer', u'integer', u'double precision', ..., u'double precision']
-
-
-.. note ::
-    If the map use postgresql it is possible to: add/rename/cast/remove columns
-    the sqlite does not support these operations.
-
-
-For people that are used to the standardized Python SQL 2.0 interface:
-
-    * http://docs.python.org/library/sqlite3.html
-    * http://www.python.org/dev/peps/pep-0249/
-
-Therefore advanced user can just use, the connect attribute to build
-a new cursor object and interact with the database. ::
-
-    >>> cur = table.conn.cursor()
-    >>> cur.execute("SELECT * FROM %s" % table.name)     # doctest: +ELLIPSIS
-    <sqlite3.Cursor object at ...>
-    >>> cur.fetchone()[:5]                               # doctest: +ELLIPSIS
-    (1, 1, 0.0, 1415.331, 2.0)
-    >>> # Close communication with the database
-    >>> cur.close()
-    >>> conn.close()
-
-
-DBlinks
----------
-
-.. autoclass:: pygrass.vector.table.DBlinks
-    :members:
-
-Link
----------
-
-.. autoclass:: pygrass.vector.table.Link
-    :members:
-
-Table
----------
-
-.. autoclass:: pygrass.vector.table.Table
-    :members:
-
-Columns
----------
-
-.. autoclass:: pygrass.vector.table.Columns
-    :members:
-
-Filters
----------
-
-.. autoclass:: pygrass.vector.table.Filters
-    :members:
-
-SQL
----------
-
-.. automodule:: pygrass.vector.sql
-    :members:
-

lib/python/pygrass/docs/vector_features.rst

@@ -1,41 +0,0 @@
-Vector Features
-===============
-
-Point
-------
-
-.. autoclass:: pygrass.vector.geometry.Point
-    :members:
-
-
-Line
------
-
-.. autoclass:: pygrass.vector.geometry.Line
-    :members:
-
-Boundary
---------
-
-.. autoclass:: pygrass.vector.geometry.Boundary
-    :members:
-
-Isle
------
-
-.. autoclass:: pygrass.vector.geometry.Isle
-    :members:
-
-
-Isles
------
-
-.. autoclass:: pygrass.vector.geometry.Isles
-    :members:
-
-Area
---------
-
-.. autoclass:: pygrass.vector.geometry.Area
-    :members:
-

lib/python/pygrass/docs/vector_utils.rst

@@ -1,27 +0,0 @@
-Vector Utils
-===============
-
-Bbox
-----
-
-.. autoclass:: pygrass.vector.basic.Bbox
-    :members:
-
-
-BoxList
---------
-
-.. autoclass:: pygrass.vector.basic.BoxList
-    :members:
-
-Ilist
------
-
-.. autoclass:: pygrass.vector.basic.Ilist
-    :members:
-
-Cats
------
-
-.. autoclass:: pygrass.vector.basic.Cats
-    :members:

man/Makefile

@@ -41,13 +41,11 @@ default: $(DSTFILES)
 	$(MAKE) $(INDICES)
 	$(call build,check)
 	$(MAKE) manpages
-	@(type $(SPHINXBUILD) > /dev/null && $(call run_pygrass_html) || (echo "WARNING: pygrass HTML documentation not compiled because 'sphinx-build' software not installed (get from http://www.sphinx.org)") ; exit 0)
 
 # This must be a separate target so that evaluation of $(MANPAGES)
 # is delayed until the indices have been generated
 manpages:
 	$(MAKE) $(MANPAGES)
-	@(type $(SPHINXBUILD) > /dev/null && $(call run_pygrass_man) || (echo "WARNING: pygrass MAN documentation not compiled because 'sphinx-build' software not installed (get from http://www.sphinx.org)") ; exit 0)
 
 .PHONY: manpages
 
@@ -69,14 +67,6 @@ GISBASE="$(RUN_GISBASE)" ARCH="$(ARCH)" ARCH_DISTDIR="$(ARCH_DISTDIR)" \
 	$(PYTHON) ./build_keywords.py $(HTMLDIR)
 endef
 
-define run_pygrass_html
-$(MAKE) -C ../lib/python/pygrass/docs/ html
-endef
-
-define run_pygrass_man
-$(MAKE) -C ../lib/python/pygrass/docs/ man
-endef
-
 $(HTMLDIR)/topics.html: $(ALL_HTML)
 	$(call build_topics)
 	touch $@