pygrass: improve documentation about grass database managment, region…

… and raster

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

lib/python/pygrass/docs/gis.rst

@@ -1,3 +1,4 @@
+.. _GRASSdatabase-label:
 
 GRASS database management
 ===============================
@@ -17,6 +18,8 @@ of GRASS database: Gisdbase, Location and Mapset
 .. autoclass:: pygrass.gis.VisibleMapset
     :members:
 
+.. _Region-label:
+
 Region management
 ======================
 

lib/python/pygrass/docs/index.rst

@@ -22,6 +22,7 @@ Contents:
    vector
    attributes
    modules
+   messages
 
 
 References

lib/python/pygrass/docs/raster.rst

@@ -153,6 +153,8 @@ 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:
 
 .. _RasterRow-label:
 
@@ -210,6 +212,8 @@ 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:
 
@@ -233,7 +237,8 @@ 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:
 
@@ -302,7 +307,8 @@ to write a single value to the map. ::
     >>> elev.close()
     >>> elev.remove()
 
-
+.. autoclass:: pygrass.raster.RasterSegment
+    :members:
 
 .. _RasterNumpy-label:
 
@@ -342,7 +348,8 @@ to load all the map in memory. ::
     True
     >>> el.remove()
 
-
+.. autoclass:: pygrass.raster.RasterNumpy
+    :members:
 
 .. _Buffer-label:
 
@@ -384,14 +391,6 @@ History
     :members:
 
 
-.. _Category-label:
-
-Category
---------
-
-.. autoclass:: pygrass.raster.category.Category
-    :members:
-
 .. _Raster library: http://grass.osgeo.org/programming7/rasterlib.html
 .. _RowIO library: http://grass.osgeo.org/programming7/rowiolib.html
 .. _Segmentation library: http://grass.osgeo.org/programming7/segmentlib.html

lib/python/pygrass/gis/__init__.py

@@ -60,6 +60,8 @@ def _check(value, path, type):
 
 
 def set_current_mapset(mapset, location=None, gisdbase=None):
+    """Set the current mapset as working area
+    """
     libgis.G_setenv('MAPSET', mapset)
     if location:
         libgis.G_setenv('LOCATION_NAME', location)
@@ -68,6 +70,7 @@ def set_current_mapset(mapset, location=None, gisdbase=None):
 
 
 def make_mapset(mapset, location=None, gisdbase=None):
+    """Create a new mapset"""
     res = libgis.G_make_mapset(gisdbase, location, mapset)
     if res == -1:
         raise GrassError("Cannot create new mapset")
@@ -83,6 +86,7 @@ class Gisdbase(object):
         >>> gisdbase.name == gisenv()['GISDBASE']
         True
 
+    ..
     """
     def __init__(self, gisdbase=''):
         self.name = gisdbase
@@ -93,7 +97,8 @@ def _get_name(self):
     def _set_name(self, name):
         self._name = _check(name, '', "GISDBASE")
 
-    name = property(fget=_get_name, fset=_set_name)
+    name = property(fget=_get_name, fset=_set_name,
+                    doc="Set or obtain the name of GISDBASE")
 
     def __str__(self):
         return self.name
@@ -122,6 +127,7 @@ def __iter__(self):
         for loc in self.locations():
             yield Location(loc, self.name)
 
+    # TODO remove or complete this function 
     def new_location(self):
         if libgis.G__make_location() != 0:
             raise GrassError("Cannot create new location")
@@ -167,15 +173,17 @@ def _get_gisdb(self):
     def _set_gisdb(self, gisdb):
         self._gisdb = _check(gisdb, '', "GISDBASE")
 
-    gisdbase = property(fget=_get_gisdb, fset=_set_gisdb)
+    gisdbase = property(fget=_get_gisdb, fset=_set_gisdb,
+                        doc="Set or obtain the name of GISDBASE")
 
     def _get_name(self):
         return self._name
 
     def _set_name(self, name):
         self._name = _check(name, self._gisdb, "LOCATION_NAME")
 
-    name = property(fget=_get_name, fset=_set_name)
+    name = property(fget=_get_name, fset=_set_name,
+                    doc="Set or obtain the name of LOCATION")
 
     def __getitem__(self, mapset):
         if mapset in self.mapsets():
@@ -198,11 +206,20 @@ def __repr__(self):
         return 'Location(%r)' % self.name
 
     def mapsets(self, pattern=None, permissions=True):
-        """Return a list of the available mapsets. ::
+        """Return a list of the available mapsets.
+
+        :param pattern: the pattern to filter the result
+        :type pattern: str
+        :param permissions: check the permission of mapset
+        :type permissions: bool
+        :returns:  a list of mapset's names
+
+        ::
 
             >>> location = Location()
             >>> location.mapsets()
             ['PERMANENT', 'user1']
+        ..
         """
         mapsets = [mapset for mapset in self]
         if permissions:
@@ -228,6 +245,8 @@ class Mapset(object):
         'nc_basic_spm_grass7'
         >>> mapset.name
         'user1'
+
+    ..
     """
     def __init__(self, mapset='', location='', gisdbase=''):
         self.gisdbase = gisdbase
@@ -241,23 +260,26 @@ def _get_gisdb(self):
     def _set_gisdb(self, gisdb):
         self._gisdb = _check(gisdb, '', "GISDBASE")
 
-    gisdbase = property(fget=_get_gisdb, fset=_set_gisdb)
+    gisdbase = property(fget=_get_gisdb, fset=_set_gisdb,
+                        doc="Set or obtain the name of GISDBASE")
 
     def _get_loc(self):
         return self._loc
 
     def _set_loc(self, loc):
         self._loc = _check(loc, self._gisdb, "LOCATION_NAME")
 
-    location = property(fget=_get_loc, fset=_set_loc)
+    location = property(fget=_get_loc, fset=_set_loc,
+                        doc="Set or obtain the name of LOCATION")
 
     def _get_name(self):
         return self._name
 
     def _set_name(self, name):
         self._name = _check(name, join(self._gisdb, self._loc), "MAPSET")
 
-    name = property(fget=_get_name, fset=_set_name)
+    name = property(fget=_get_name, fset=_set_name,
+                    doc="Set or obtain the name of MAPSET")
 
     def __str__(self):
         return self.name
@@ -281,6 +303,11 @@ def glist(self, type, pattern=None):
             * 'vect',
             * 'view3d'
 
+        :param type: the type of element to query
+        :type type: str
+        :param pattern: the pattern to filter the result
+        :type pattern: str
+
         ::
 
             >>> mapset = Mapset('PERMANENT')
@@ -290,6 +317,8 @@ def glist(self, type, pattern=None):
             ['basins', 'elevation', ...]
             >>> mapset.glist('rast', pattern='el*')
             ['elevation_shade', 'elevation']
+
+        ..
         """
         if type not in ETYPE:
             str_err = "Type %s is not valid, valid types are: %s."
@@ -307,6 +336,7 @@ def glist(self, type, pattern=None):
                 return elist
 
     def is_current(self):
+        """Check if the MAPSET is the working MAPSET"""
         return (self.name == libgis.G_getenv('MAPSET') and
                 self.location == libgis.G_getenv('LOCATION_NAME') and
                 self.gisdbase == libgis.G_getenv('GISDBASE'))
@@ -331,6 +361,8 @@ class VisibleMapset(object):
         >>> mapset = VisibleMapset('user1')
         >>> mapset
         ['user1', 'PERMANENT']
+
+    ..
     """
     def __init__(self, mapset, location='', gisdbase=''):
         self.mapset = mapset
@@ -357,27 +389,43 @@ def read(self):
         return lns
 
     def _write(self, mapsets):
-        """Write to SEARCH_PATH file the changes in the search path"""
+        """Write to SEARCH_PATH file the changes in the search path
+
+        :param mapsets: a list of mapset's names
+        :type mapsets: list
+        """
         with open(self.spath, "w+") as f:
             ms = self.location.mapsets()
             f.write('%s' % '\n'.join([m for m in mapsets if m in ms]))
 
     def add(self, mapset):
-        """Add a mapset to the search path"""
+        """Add a mapset to the search path
+
+        :param mapset: a mapset's name
+        :type mapset: str
+        """
         if mapset not in self.read() and mapset in self.location:
             with open(self.spath, "a+") as f:
                 f.write('\n%s' % mapset)
         else:
             raise TypeError('Mapset not found')
 
     def remove(self, mapset):
-        """Remove mapset to the search path"""
+        """Remove mapset to the search path
+
+        :param mapset: a mapset's name
+        :type mapset: str
+        """
         mapsets = self.read()
         mapsets.remove(mapset)
         self._write(mapsets)
 
     def extend(self, mapsets):
-        """Add more mapsets to the search path"""
+        """Add more mapsets to the search path
+        
+        :param mapsets: a list of mapset's names
+        :type mapsets: list
+        """
         ms = self.location.mapsets()
         final = self.read()
         final.extend([m for m in mapsets if m in ms and m not in final])