PyGRASS docs cosmentics

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

lib/python/docs/src/pygrass_gis.rst

@@ -1,21 +1,30 @@
 .. _GRASSdatabase-label:
 
 GRASS database management
-===============================
+=========================
 
-These classes are used to manage the infrastructure
-of GRASS database: Gisdbase, Location and Mapset
+PyGRASS imlements the classes described bellow:
 
-Details about the GRASS GIS database management (locations and mapsets)
-can be found in the `GRASS GIS 7 User's Manual: GRASS GIS Quickstart <http://grass.osgeo.org/grass73/manuals/helptext.html>`_
+* :class:`~pygrass.gis.Gisdbase`
+* :class:`~pygrass.gis.Location`
+* :class:`~pygrass.gis.Mapset`
+* :class:`~pygrass.gis.VisibleMapset`
+  
+These classes are used to manage the infrastructure of GRASS database:
+GIS data directory, Location and Mapset. Details about the GRASS GIS
+database management (locations and mapsets) can be found in the `GRASS
+GIS 7 User's Manual: GRASS GIS Quickstart
+<http://grass.osgeo.org/grass73/manuals/helptext.html>`_.
 
 .. _Region-label:
 
 Region management
-======================
+=================
 
-The Region class it is useful to obtain information
-about the computational region and to change it.
+The :class:`~pygrass.gis.region.Region` class it is useful to obtain
+information about the computational region and to change it. Details
+about the GRASS GIS computational region management can be found in
+the `GRASS GIS Wiki: Computational region
+<http://grasswiki.osgeo.org/wiki/Computational_region>`_.
 
-Details about the GRASS GIS computational region management can be found
-in the `GRASS GIS Wiki: Computational region <http://grasswiki.osgeo.org/wiki/Computational_region>`_
+The classes are part of the :mod:`~pygrass.gis` module.

lib/python/docs/src/pygrass_index.rst

@@ -1,12 +1,12 @@
 PyGRASS documentation
-===================================
+=====================
 
 Python is a programming language which is more powerful than shell
-scripting but easier and more forgiving than C. ``PyGRASS`` is an
+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
+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``
+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
@@ -17,15 +17,15 @@ 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).
+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.
+Read more about how to work with *PyGRASS* in this documentation.
 
-Contents:
+**Contents:**
 
 .. toctree::
    :maxdepth: 2
@@ -39,14 +39,22 @@ Contents:
 
 
 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>`_
-* `GRASS GIS 7 Programmer's Manual <http://grass.osgeo.org/programming7/>`_
-
-This project has been funded with support from the `Google Summer of Code 2012 <http://trac.osgeo.org/grass/wiki/GSoC#PythonhighlevelmapinteractionforGRASSGIS>`_
-
+^^^^^^^^^^
+
+* 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>`_
+* `GRASS GIS 7 Programmer's Manual
+  <http://grass.osgeo.org/programming7/>`_
+
+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

lib/python/docs/src/pygrass_messages.rst

@@ -1,12 +1,14 @@
 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>`_.
-
-This class implements a fast and exit-safe interface to the GRASS
-C-library message functions like: G_message(), G_warning(),
-G_important_message(), G_verbose_message(), G_percent() and G_debug().
+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>`_.
+
+The :class:`~pygrass.messages.Messenger` class implements a fast and
+exit-safe interface to the GRASS C-library message functions like:
+``G_message()``, ``G_warning()``, ``G_important_message()``,
+``G_verbose_message()``, ``G_percent()`` and ``G_debug()``.
 
 Usage:
 

lib/python/docs/src/pygrass_modules.rst

@@ -1,9 +1,11 @@
 Interface to GRASS GIS modules
 ==============================
 
-In "modules", GRASS GIS modules are represented as objects. These objects
-are generated based on the XML module description that is used also for
-the generation of the graphical user interface (GUI). ::
+In :mod:`~pygrass.modules` module, GRASS GIS modules are represented
+by :class:`~pygrass.modules.interface.module.Module` class
+objects. These objects are generated based on the XML module
+description that is used also for the generation of the graphical user
+interface (GUI). ::
 
     >>> from grass.pygrass.modules import Module
     >>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
@@ -138,7 +140,7 @@ For each input and output parameter it is possible to obtain specific
 information. To see all module inputs, just type: ::
 
     >>> slope_aspect.inputs #doctest: +NORMALIZE_WHITESPACE
-    TypeDict([('elevation', Parameter <elevation> (required:yes, type:raster, multiple:no)), ('format', Parameter <format> (required:no, type:string, multiple:no)), ('prec', Parameter <prec> (required:no, type:string, multiple:no)), ('zfactor', Parameter <zfactor> (required:no, type:float, multiple:no)), ('min_slp_allowed', Parameter <min_slp_allowed> (required:no, type:float, multiple:no))])
+    TypeDict([('elevation', Parameter <elevation> (required:yes, type:raster, multiple:no)), ('format', Parameter <format> ...)])
 
 To get information for each parameter: ::
 
@@ -204,6 +206,16 @@ Another example of use: ::
     >>> category = Module("r.category", map="elevation",
     ...                   stdin_=info.popen.stdout, finish_=True)
 
+Launching GRASS GIS modules in parallel
+---------------------------------------
 
+PyGRASS implements simple mechanism for launching GRASS modules in
+parallel. See
+:class:`~pygrass.modules.interface.module.ParallelModuleQueue` class
+for details.
 
+Multiple GRASS modules can be joined into one object by
+:class:`~pygrass.modules.interface.module.MultiModule`.
+
+    
 .. _Popen: http://docs.python.org/library/subprocess.html#Popen

lib/python/docs/src/pygrass_raster.rst

@@ -4,18 +4,20 @@ Introduction to Raster classes
 ==============================
 
 Details about the GRASS GIS raster architecture can be found in the
-`GRASS GIS 7 Programmer's Manual: GRASS Raster Library <http://grass.osgeo.org/programming7/rasterlib.html>`_
-
-PyGRASS uses 3 different Raster classes, that respect the 3 different approaches
-of GRASS-C API. The classes use a standardized interface to keep methods
-consistent between them. The read access is row wise for :ref:`RasterRow-label`
-and :ref:`RasterRowIO-label` and additionally
-cached in the RowIO class. Both classes write sequentially.
-RowIO is row cached, :ref:`RasterSegment-label` 
-is tile cached for reading and writing; therefore, random access is possible.
-Hence RasterRow and RasterRowIO should be used for fast (cached)
-row read access and RasterRow for fast sequential writing.
-RasterSegment should be used for random access.
+`GRASS GIS 7 Programmer's Manual: GRASS Raster Library
+<http://grass.osgeo.org/programming7/rasterlib.html>`_.
+
+PyGRASS uses 3 different raster classes, that respect the 3 different
+approaches of GRASS-C API. The classes use a standardized interface to
+keep methods consistent between them. The read access is row wise for
+:ref:`RasterRow-label` and :ref:`RasterRowIO-label` and additionally
+cached in the RowIO class. Both classes write sequentially.  RowIO is
+row cached, :ref:`RasterSegment-label` is tile cached for reading and
+writing; therefore, random access is possible.  Hence RasterRow and
+RasterRowIO should be used for fast (cached) row read access and
+RasterRow for fast sequential writing.  RasterSegment should be used
+for random access. The classes are part of the :mod:`~pygrass.raster`
+module.
 
 
 ==========================  =======================  ========  ============
@@ -64,12 +66,12 @@ We can rename the map: ::
 RasterRow
 ---------
 
-The PyGrass :class:`~pygrass.raster.RasterRow` class allow user to open maps row
+The PyGRASS :class:`~pygrass.raster.RasterRow` class allow user to open maps row
 by row in either read or write mode using the `Raster library`_. Reading and writing
 to the same map at the same time is not supported. For this functionality,
 please see the :ref:`RasterSegment-label` class.
 The RasterRow class allows map rows to be read in any order, but map rows can
-only be written in sequential order. Therefore, each now row written to a map is
+only be written in sequential order. Therefore, each row written to a map is
 added to the file as the last row. ::
 
     >>> raster = reload(raster)
@@ -124,7 +126,7 @@ RasterRowIO
 The :class:`~pygrass.raster.RasterRowIO` class uses the GRASS `RowIO library`_, and implements a row
 cache. The RasterRowIO class only supports reading rasters; because raster rows
 can only be written in sequential order, writing by row id is not
-supported by design. Hence, the rowio lib can only be used to cache rows
+supported by design. Hence, the RowIO lib can only be used to cache rows
 for reading, and any write access should use the :ref:`RasterRow-label` class. ::
 
     >>> raster = reload(raster)
@@ -174,7 +176,7 @@ opening maps in a read-write mode. ::
 Due to the unique behavior of this class, the RasterSegment class defines two
 methods to read a map:
 
-    * ``get_row`` calls the C function ``Segment_get_row`` and returns a buffer
+    * ``get_row`` calls the C function ``Segment_get_row()`` and returns a buffer
       object with the row. ::
 
         >>> # call explicitly the method
@@ -182,7 +184,7 @@ methods to read a map:
         >>> # call implicitly the method
         >>> elev_row0 = elev[0]
 
-    * ``get`` calls the C function ``Segment_get`` and returns the value of the
+    * ``get`` calls the C function ``Segment_get()`` and returns the value of the
       map cell. ::
 
         >>> # call explicitly the method
@@ -190,8 +192,8 @@ methods to read a map:
         >>> # call implicitly the method
         >>> elev_val_0_0 = elev[0, 0]
 
-Similarly, writing to a map uses two methods: ``put_row`` to write a row and
-``put`` to write a single value to the map. ::
+Similarly, writing to a map uses two methods: ``put_row()`` to write a row and
+``put()`` to write a single value to the map. ::
 
     >>> # compare the cell value get using the ``get`` method, and take the first
     >>> # value of the row with the ``get_row`` method

lib/python/docs/src/pygrass_vector.rst

@@ -2,21 +2,25 @@ Introduction to Vector classes
 ==============================
 
 Details about the GRASS GIS vector architecture can be found in the
-`GRASS GIS 7 Programmer's Manual: GRASS Vector Library <http://grass.osgeo.org/programming7/vectorlib.html>`_
+`GRASS GIS 7 Programmer's Manual: GRASS Vector Library
+<http://grass.osgeo.org/programming7/vectorlib.html>`_.
 
-PyGrass has two classes for vector maps: :ref:`Vector-label` and :ref:`VectorTopo-label`.
-As the names suggest, the Vector class is for vector maps, while VectorTopo
-opens vector maps with `GRASS GIS topology <http://grass.osgeo.org/programming7/vlibTopology.html>`_.
-VectorTopo is an extension of the Vector class, so supports all the Vector class methods, with additions.
+PyGRASS has two classes for vector maps: :ref:`Vector-label` and
+:ref:`VectorTopo-label`.  As the names suggest, the Vector class is
+for vector maps, while VectorTopo opens vector maps with `GRASS GIS
+topology <http://grass.osgeo.org/programming7/vlibTopology.html>`_.
+VectorTopo is an extension of the Vector class, so supports all the
+Vector class methods, with additions. The classes are part of the
+:mod:`~pygrass.vector` module.
 
 .. _Vector-label:
 
 Vector
 ------
 
-The :class:`~pygrass.vector.Vector` class is part of the :mod:`~pygrass.vector`
-module. It is based on the :class:`~pygrass.vector.abstract.Info` class, which
-provides methods for accessing basic information about the vector map: ::
+The :class:`~pygrass.vector.Vector` class is based on the
+:class:`~pygrass.vector.abstract.Info` class, which provides methods
+for accessing basic information about the vector map: ::
 
     >>> from grass.pygrass.vector import Vector
     >>> cens = Vector('census')
@@ -55,8 +59,8 @@ like the Vector class: ::
     'user1'
 
 
-Working with Vector Objects
----------------------------
+Working with Vector Maps
+------------------------
 
 As the VectorTopo class is so similar to the Vector class, the following examples
 exclusively demonstrate the VectorTopo class.
@@ -67,13 +71,16 @@ To begin using a vector map, it must first be opened: ::
     >>> municip = VectorTopo('boundary_municp_sqlite')
     >>> municip.open(mode='r')
 
-The ``open()`` method supports a number of option arguments (see the :class:`~pygrass.vector.abstract.Info`
-documentation for a complete list). In particular, the mode argument can take a
-a value of:
+The ``open()`` method supports a number of option arguments (see the
+:class:`~pygrass.vector.abstract.Info` documentation for a complete
+list). In particular, the mode argument can take a a value of:
 
-'r': read-only mode, vector features are read-only (attribute table is modifiable since are handle by a database);
-'w': write-only mode, write a new vector map in case of an old vector map all the previous features will be removed/overwritten;
-'rw': read-write mode, add new/update vector features without removing the existing ones. Add/remove vector layers.
+* 'r': read-only mode, vector features are read-only (attribute table
+  is modifiable since are handle by a database);
+* 'w': write-only mode, write a new vector map in case of an old
+  vector map all the previous features will be removed/overwritten;
+* 'rw': read-write mode, add new/update vector features without
+  removing the existing ones. Add/remove vector layers.
 
 
 The geometry of a vector map can be read sequentially using the ``next()`` method.
@@ -118,7 +125,7 @@ Write the two points to the map:
     >>> new.write(point0, cat=1, attrs=('pub',))
     >>> new.write(point1, cat=2, attrs=('resturant',))
 
-Commit the db changes:
+Commit the DB changes (attributes):
 
     >>> new.table.conn.commit()
     >>> new.table.execute().fetchall()
@@ -208,19 +215,25 @@ requesting the table from each of the returned links: ::
     Link(1, census, sqlite)
     >>> table = link.table()
 
-Here, ``DBlinks()`` is a class (:class:`~pygrass.vector.table.DBlinks`) that
-contains all the links of a vector map. Each link is also a class
+Here, :class:`~pygrass.vector.table.DBlinks` is a class that contains
+all the links of a vector map. Each link is also a class
 (:class:`~pygrass.vector.table.Link`) that contains a specific link's
-parameters. The ``table()`` method of the link class return the linked table as
-a table object (:class:`~pygrass.vector.table.Table`).
+parameters. The ``table()`` method of the link class return the linked
+table as a table object (:class:`~pygrass.vector.table.Table`).
 
 Geometry Classes
 ----------------
 
-The vector package also includes a number of geometry classes, including Area,
-Boundary, Centroid, Isle, Line, and Point classes. Please consult the
-:mod:`~pygrass.vector.geometry` module for a complete list of methods for these
-classes, as there are many. Some basic examples are given below.
+The vector package also includes a number of geometry classes,
+including :class:`~pygrass.vector.geometry.Area`,
+:class:`~pygrass.vector.geometry.Boundary`,
+:class:`~pygrass.vector.geometry.Centroid`,
+:class:`~pygrass.vector.geometry.Isle`,
+:class:`~pygrass.vector.geometry.Line`, and
+:class:`~pygrass.vector.geometry.Point` classes. Please consult the
+:mod:`~pygrass.vector.geometry` module for a complete list of methods
+for these classes, as there are many. Some basic examples are given
+below.
 
 Instantiate a Point object that could be 2 or 3D, default parameters are 0: ::
 
@@ -278,7 +291,7 @@ Find all areas larger than 10000m2: ::
     >>> big = [area for area in municip.viter('areas')
     ...        if area.alive() and area.area >= 10000]
 
-The PyGrass vector methods make complex operations rather easy. Notice the
+The PyGRASS vector methods make complex operations rather easy. Notice the
 ``viter()`` method: this returns an iterator object of the vector features, so
 the user can choose on which vector features to iterate without loading all the
 features into memory.
@@ -293,7 +306,6 @@ We can then sort the areas by size: ::
     Area(2682) 320224369.66
     Area(2552) 298356117.948
 
-
 Or sort for the number of isles that are contained inside: ::
 
     >>> big.sort(key = lambda x: x.isles.__len__(), reverse = True)