python docs: documentation improved

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

lib/python/docs/src/gunittest_running_tests.rst

@@ -1,5 +1,5 @@
-Running the tests of GRASS GIS
-==============================
+Running the test framework of GRASS GIS
+=======================================
 
 This is an advanced guide to running tests of GRASS GIS using GRASS
 testing framework (`gunittest`).
@@ -76,4 +76,4 @@ using ``crontab -e`` and adding the following line::
 
     0 4 * * 1 /home/vpetras/grasstests/test_grass_gis.sh
 
-Which will perform the tests every Monday at 4 in the morning.
+Which will perform the tests every Monday at 4am in the (North Carolina) morning.

lib/python/docs/src/index.rst

@@ -1,6 +1,29 @@
 GRASS GIS Python library documentation
 ==========================================
 
+Python, a widely used general-purpose, high-level programming language 
+provides a powerful scripting interface. Being easy-to-use yet 
+powerful, it enables users to efficiently exploit the capabilities of 
+the GRASS GIS software. Python scripts for GRASS GIS can be written at 
+high level (GRASS GIS modules) as well as at low level (GRASS GIS 
+libraries) through a dedicated interface. The graphical user interface 
+and the GRASS GIS Temporal Framework are entirely written in Python.
+
+A set of packages is provided to the user in order to provide functionality
+at various levels:
+
+* **script package**: Python interface to launch GRASS GIS modules in scripts
+* **PyGRASS documentation**: PyGRASS is an object-oriented Python Application 
+  Programming Interface (API) for GRASS GIS which uses the GRASS C API as 
+  backend but additionally offers a convenient interface to the GRASS GIS 
+  modules
+* **GRASS GIS Temporal Framework**: implements the temporal GIS functionality
+  of GRASS GIS and provides an API to implement spatio-temporal processing modules
+* **exceptions package**: FIXME
+* **imaging package**: library to create animated images and films
+* **Testing GRASS GIS source code and modules**: (gunittest package
+* **pydispatch package**: Multiple-producer-multiple-consumer signal-dispatching
+
 Contents:
 
 .. toctree::

lib/python/docs/src/pygrass_vector.rst

@@ -1,5 +1,3 @@
-.. _vector-label:
-
 Introduction to Vector classes
 ==============================
 

lib/python/docs/src/temporal_framework.rst

@@ -1,4 +1,4 @@
-The GRASS GIS Temporal Framework
+GRASS GIS Temporal Framework
 ================================
 
 Introduction

lib/python/exceptions/__init__.py

@@ -1,4 +1,5 @@
-# -*- coding: utf-8 -*-
+"""GRASS GIS interface to Python exceptions
+"""
 
 import subprocess
 

lib/python/gunittest/Makefile

@@ -7,6 +7,7 @@ PYDIR = $(ETC)/python
 GDIR = $(PYDIR)/grass
 DSTDIR = $(GDIR)/gunittest
 
+# TODO: add multireport multirunner
 MODULES = case gmodules loader runner checkers gutils invoker main reporters utils
 
 PYFILES := $(patsubst %,$(DSTDIR)/%.py,$(MODULES) __init__)

lib/python/gunittest/__init__.py

@@ -1,15 +1,12 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest
-
-@brief GRASS Python testing framework module for running from command line
+"""GRASS Python testing framework module for running from command line
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
-@author Soeren Gebbert
+:authors: Vaclav Petras, Soeren Gebbert
 
 Initial version of `gunittest` was created during Google Summer of Code 2014
 by Vaclav Petras as a student and Soeren Gebbert as a mentor.

lib/python/gunittest/case.py

@@ -1,15 +1,12 @@
 # -*- coding: utf-8 -*-
-
-"""!@package grass.gunittest.case
-
-@brief GRASS Python testing framework test case
+"""GRASS Python testing framework test case
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
-License (>=v2). Read the file COPYING that comes with GRASS
+License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 """
 
 import os

lib/python/gunittest/checkers.py

@@ -1,16 +1,12 @@
 # -*- coding: utf-8 -*-
-
-"""!@package grass.gunittest.checkers
-
-@brief GRASS Python testing framework checkers
+"""GRASS Python testing framework checkers
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
-License (>=v2). Read the file COPYING that comes with GRASS
+License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
-@author Soeren Gebbert
+:authors: Vaclav Petras, Soeren Gebbert
 """
 
 import sys

lib/python/gunittest/gmodules.py

@@ -1,16 +1,14 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.gmodules
-
-@brief Specialized interfaces for invoking modules for testing framework
+"""Specialized interfaces for invoking modules for testing framework
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
-@author Soeren Gebbert
+:authors: Vaclav Petras, Soeren Gebbert
 """
+
 import subprocess
 from grass.script.core import start_command
 from grass.exceptions import CalledModuleError

lib/python/gunittest/gutils.py

@@ -1,17 +1,15 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.gutils
-
-@brief Utilities related to GRASS GIS for GRASS Python testing framework
+"""Utilities related to GRASS GIS for GRASS Python testing framework
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 """
-from .gmodules import call_module
 
+from .gmodules import call_module
 
 def get_current_mapset():
     """Get curret mapset name as a string"""

lib/python/gunittest/invoker.py

@@ -1,14 +1,12 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.invoker
-
-@brief GRASS Python testing framework test files invoker (runner)
+"""GRASS Python testing framework test files invoker (runner)
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 """
 
 import os

lib/python/gunittest/loader.py

@@ -1,14 +1,12 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.loader
-
-@brief GRASS Python testing framework test loading functionality
+"""GRASS Python testing framework test loading functionality
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 """
 
 import os

lib/python/gunittest/main.py

@@ -1,14 +1,12 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.main
-
-@brief GRASS Python testing framework module for running from command line
+"""GRASS Python testing framework module for running from command line
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 """
 
 import os

lib/python/gunittest/multireport.py

@@ -1,4 +1,14 @@
 # -*- coding: utf-8 -*-
+"""Testing framework module for multi report
+
+Copyright (C) 2014 by the GRASS Development Team
+This program is free software under the GNU General Public
+License (>=v2). Read the file COPYING that comes with GRASS GIS
+for details.
+
+:authors: Vaclav Petras
+"""
+
 
 import sys
 import os

lib/python/gunittest/multirunner.py

@@ -1,4 +1,13 @@
 # -*- coding: utf-8 -*-
+"""Testing framework module for running tests in Python unittest fashion
+
+Copyright (C) 2014 by the GRASS Development Team
+This program is free software under the GNU General Public
+License (>=v2). Read the file COPYING that comes with GRASS GIS
+for details.
+
+:authors: Vaclav Petras
+"""
 
 from __future__ import print_function
 

lib/python/gunittest/reporters.py

@@ -1,17 +1,14 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.reporters
-
-@brief GRASS Python testing framework module for report generation
+"""GRASS Python testing framework module for report generation
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 """
 
-
 import os
 import datetime
 import xml.sax.saxutils as saxutils

lib/python/gunittest/runner.py

@@ -1,14 +1,12 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.runner
-
-@brief Testing framework module for running tests in Python unittest fashion
+"""Testing framework module for running tests in Python unittest fashion
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 
 File content taken from Python's  ``unittest.runner``, it will be used as
 a template. It is not expected that something will left.

lib/python/gunittest/utils.py

@@ -1,14 +1,12 @@
 # -*- coding: utf-8 -*-
-"""!@package grass.gunittest.utils
-
-@brief GRASS Python testing framework utilities (general and test-specific)
+"""GRASS Python testing framework utilities (general and test-specific)
 
 Copyright (C) 2014 by the GRASS Development Team
 This program is free software under the GNU General Public
 License (>=v2). Read the file COPYING that comes with GRASS GIS
 for details.
 
-@author Vaclav Petras
+:authors: Vaclav Petras
 """
 
 import os

lib/python/script/__init__.py

@@ -1,3 +1,6 @@
+"""Python interface to launch GRASS GIS modules in scripts
+"""
+
 from core   import *
 from db     import *
 from raster import *