Merge pull request #14 from ibaris/documentation

Documentation

docs/conf.py

@@ -83,7 +83,7 @@
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
-# This is also used if you do content translation via gettext catalogs.
+# This is also used if you're doing content translations via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = None
 
@@ -98,19 +98,19 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
+# The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
+# further. For a list of options available for each theme, see the
 # documentation.
 #
 # html_theme_options = {}
 
-# Add any paths that contain custom static files (such as style sheets) here,
+# Add paths that contains custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']

docs/database.rst

@@ -1,11 +1,10 @@
 Database Related Modules
 ------------------------
-In this section modules are listed which relate to GRASS GIS databases. The modules listed below can create databases
-and mapsets. In this section modules are listed which relate to GRASS GIS databases. The modules listed below can create
-databases and mapsets.
+In this section, modules are listed which relate to GRASS GIS databases. The modules listed below can create databases
+and mapsets.
 
 The modules work with GRASS GIS versions ``['grass70', 'grass71', 'grass72', 'grass73', 'grass74']``.
-However, this can be easily extended. To extend the versions add new GRASS GIS versions to ``self.candidates`` in
+However, this can easily be extended. To extend the versions, add new GRASS GIS versions to ``self.candidates`` in
 ``gscpy.g_db.g_c_database``.
 
 The name of the modules was chosen to ensure conformity with the GRASS GIS conventions. The addition c was added to

docs/download.rst

@@ -1,7 +1,7 @@
 Download Related Modules
 ------------------------
-This module makes searching, downloading and retrieving the metadata of Sentinel satellite images from the Copernicus
-Open Access Hub easy.
+This module makes searching, downloading and retrieving metadata of Sentinel 1 satellite images, from the Copernicus
+Open Access Hub, easy.
 
 .. automodule:: gscpy.ds1_download.ds1_download
    :members: S1Download

docs/ds1_download_example.rst

@@ -1,6 +1,6 @@
 Sentinel 1 Downloader
 ---------------------
-Here is an example how to use the sentinel downloader to map all available data `(flag: -p)`::
+Here is an example of how to use the Sentinel downloader, to map all available data `(flag: -p)`::
 
     $ ds1.download -p username=DALEK password=exterminate region=myGEoJsOnFile.geojson timestart=2015-01-02
       timeend=2015-01-12 outdir='home/usr/data' producttype=SLC
@@ -14,7 +14,7 @@ Type your Username and Password:
    :alt: Create a Mapset
    :align: center
 
-After the definition of a region with a geojson file one can specify the sensing period and the polarization and the
+After the definition of a region with a geojson file you can specify the sensing period, polarization and the
 product type:
 
 .. image:: _static/ds1_download_1.png
@@ -32,7 +32,7 @@ product type:
    :alt: Create a Mapset
    :align: center
 
-With `flag -p` one can print all available products. If the flag is missing the data will be downloaded:
+With `flag -p` you can print all available products. If the flag is missing all data will be downloaded:
 
 .. image:: _static/ds1_download_4.png
    :scale: 50 %

docs/example.rst

@@ -1,12 +1,25 @@
 Examples
 ========
-Here are some examples how you can use the gscpy package with GRASS GIS. In the examples most of the modules are
+Here are some examples of how you can use the gscpy package with GRASS GIS. In the examples most of the modules are
 executed within the GRASS terminal. It is also possible to do all these steps with the graphical GUI. Most of the
-examples here are from `FOSS4G 2014 workshop`_
+examples are from `FOSS4G 2014 workshop`_
 
 .. _FOSS4G 2014 workshop: http://ncsu-geoforall-lab.github.io/grass-temporal-workshop/
 
-Contents:
+
+Data
+----
+These data are from `here`_. These data are already in a GRASS GIS database. To show the import routines I exported the
+files within the mapset `climate_2000_2012` with `out.l.gdal`. This mapset contains temperature and precipitation series
+for North Carolina from `State Climate Office of North Carolina`_.
+
+
+.. _here: http://fatra.cnr.ncsu.edu/temporal-grass-workshop/NC_spm_temporal_workshop.zip
+.. _State Climate Office of North Carolina: http://convection.meas.ncsu.edu:8080/thredds/catalog/catalog.html
+
+Contents
+--------
+
 
 .. toctree::
    :maxdepth: 2

docs/export.rst

@@ -1,6 +1,6 @@
 Export Related Modules
 -----------------------
-Exports GRASS raster maps from a selection into GDAL supported formats.
+Exports GRASS raster maps from a selection into formats which GDAL supports.
 
 .. automodule:: gscpy.out_l_export.out_l_gdal
    :members: OutLGdal

docs/g_c_mapset_example.rst

@@ -1,6 +1,6 @@
 Create a Mapset
 ---------------
-Start GRASS with a location and create a mapset `climate_2000_2012`. Therefore, one can use ``g.c.mapset``::
+Start GRASS with a location and create a mapset `climate_2000_2012`. Therefore, you can use ``g.c.mapset``::
 
     $ g.c.mapset mapset=climate_2000_2012
 

docs/i_dr_input_example.rst

@@ -1,18 +1,18 @@
 Import / Export Raster Files
 ----------------------------
-After we downloaded the data (See section Data), we can list all available raster files within the directors
-`climate_2000_2012`. We use the module ``i.dr.import``::
+After downloading the data (See section Data), you can list all available raster files within the directory
+`climate_2000_2012`, by using the module ``i.dr.import``::
 
     $ i.dr.input -p input_dir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012
 
-We can see now all files:
+Now you can see all files:
 
 .. image:: _static/i_dr_import_0.png
    :scale: 50 %
    :alt: Create a Mapset
    :align: center
 
-To show the ``pattern`` parameter of the module ``i.dr.import`` now we want to consider only files that has the string
+To show the ``pattern`` parameter of the module ``i.dr.import`` we want to consider only files that has the string
 `tempmean` in their filenames::
 
     $ i.dr.input -p input_dir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012 pattern=.*tempmean
@@ -26,8 +26,8 @@ With the command::
 
     $ i.dr.input input_dir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012
 
-we can import all raster files located in `/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012`. To be sure
-we can we can use the command::
+you can import all raster files located in `/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012`. To be sure
+you can use the command::
 
     $ g.list type=raster
 
@@ -36,11 +36,11 @@ we can we can use the command::
    :alt: Create a Mapset
    :align: center
 
-We could export all files with the command ``out.l.gdal`` like::
+You could export all files with the command ``out.l.gdal`` like::
 
     $ out.l.gdal type=raster outdir=/media/ibaris/Shared/Documents/NC_DATA/climate_2000_2012
 
-With the `flag: -p` we can see the files that will be exported:
+With the `flag: -p` you can see the files that will be exported:
 
 .. image:: _static/out_l_gdal_0.png
    :scale: 50 %

docs/import.rst

@@ -1,8 +1,8 @@
 Import Related Modules
 ----------------------
 These modules are for importing data. Unlike the existing modules, they can import all files in a directory
-with considering a certain pattern. Moreover, it is possible to import these data in different ``mapsets``. In addition,
-the module ``i_fr_import`` can import ``pyroSAR`` dataset in a directory based on their metadata.
+by considering a certain pattern. Moreover, it is possible to import these data in different ``mapsets``. In addition,
+the module ``i_fr_import`` can import ``pyroSAR`` datasets in a directory based on their metadata.
 
 The name of the modules was chosen to ensure conformity with the GRASS GIS conventions. The addition ``r`` stands for
 *raster* where the addition ``d`` and ``f`` stand for *directory* and *finder* respectively.

docs/import_script.rst

@@ -2,7 +2,7 @@ Import Scripts
 --------------
 Import Scripts from a package to GRASS GIS.
 
-This class will copy any suitable python file like 'i_dr_import.py' into the GRASS script folder without
+This class will copy any suitable python file like 'i_dr_import.py' into the GRASS script folder, without
 the '.py' extension and changes the name to 'i.dr.import'. This class will exclude such files like
 '__init__.py' or 'setup.py'. For more exclusions the parameter `exclusion` can be used.
 

docs/installation.rst

@@ -4,11 +4,11 @@ After you have received the `gscpy` package, you can install it with
 ::
     $ python setup.py install
 
-After this process it is advantageous to use the script ``i_script`` with GRASS GIS. This is necessary because some
+After this process it is recommended to use the script ``i_script`` with GRASS GIS. This is necessary because some
 modules from this package call other modules from this package that are only present if they are located in the
 script folder of GRASS GIS. It is possible that some of these modules require administration rights. The reason for
-this is that, for example, when downloading data to the hard disk, any write permissions must be present. Thus,
-here the launch process is proceeded with ``sudo``::
+this is that, for example, when downloading data to the hard disk, any write permissions must be present. Therefor,
+the launch process is proceeded with ``sudo``::
     $ sudo grass
 
 To launch a Python script from GUI, use File -> Launch Python script and select /path/to/gscpy/i_script.py.
@@ -18,7 +18,7 @@ Now you can launch the following modules:
     * g.database: Create a GRASS GIS Database.
     * g.c.mapset: Create a mapset in a GRASS GIS Database if it is not existent.
     * s1.download: Data download including basic adjustments for Sentinel-1 with `sentinelsat`_.
-    * i.dr.import: Import data into a mapset from a file with considering a certain pattern.
+    * i.dr.import: Import data into a mapset from a file by considering a certain pattern.
     * i.fr.import: Import pyroSAR dataset in a directory based on their metadata.
     * pr.geocode: Wrapper function for geocoding SAR images using `pyroSAR`_.
     * t.c.register: Creation of Sentinel-1 space-time cube.

docs/introduction.rst

@@ -9,15 +9,15 @@ use this module to search for newly processed files and import them into a datab
 Here is an overview of the content:
 
     * A simple module that import Scripts from a package to GRASS GIS script directory.
-    * Database management modules where one can create entire databases or mapsets.
+    * Database management modules where it is possible to create create entire databases or mapsets.
     * Data download including basic adjustments for Sentinel-1 with `sentinelsat`_.
     * A SAR pre-processing add-on for GRASS GIS based on SNAP processing workflow which uses `pyroSAR`_.
-    * Modules to import all files in a directory with considering a certain pattern.  Moreover, it is possible to import
+    * Modules to import all files in a directory by considering a certain pattern.  Moreover, it is possible to import
       these data in different ``mapsets``.
-    * Module that can import ``pyroSAR`` dataset in a directory based on their metadata.
+    * A module that can import ``pyroSAR`` dataset in a directory based on their metadata.
     * Creation of space-time cube.
 
-The package `pyroSAR`_ and `sentinelsat`_ is used for the pre-processing and download of sentinel data respectively.
+The package `pyroSAR`_ and `sentinelsat`_ is used for the pre-processing and download of sentinel data.
 
 Modules
 -------
@@ -26,8 +26,8 @@ This packages include the following modules:
     * g.database: Create a GRASS GIS Database.
     * g.c.mapset: Create a mapset in a GRASS GIS Database if it is not existent.
     * s1.download: Data download including basic adjustments for Sentinel-1 with `sentinelsat`_.
-    * i.dr.import: Import data into a mapset from a file with considering a certain pattern.
-    * i.fr.import: Import pyroSAR dataset in a directory based on their metadata.
+    * i.dr.import: Import data into a mapset from a file by considering a certain pattern.
+    * i.fr.import: Import pyroSAR datasets in a directory based on their metadata.
     * pr.geocode: Wrapper function for geocoding SAR images using `pyroSAR`_.
     * t.c.register: Creation of Sentinel-1 space-time cube.
 

docs/pre_process.rst

@@ -2,8 +2,8 @@ Pre-Processing Related Modules
 -------------------------------
 Wrapper function for geocoding SAR images using `pyroSAR`_:
 
-    | The pyroSAR package aims at providing a complete solution for the scalable organization and processing of SAR
-    | satellite data:
+    | The purpose of the pyroSAR package is to provide a complete solution for the scalable organization and
+    | processing of SAR satellite data:
     |
     | * Reading of data from various past and present satellite missions
     | * Handling of acquisition metadata

docs/t_c_register_example.rst

@@ -1,7 +1,7 @@
 Spatio-temporal data handling
 -----------------------------
 To better handle the long time series of maps, we create temporal datasets which serve as containers for the time
-series and we will further manipulate them instead of the individual maps. Usually, we create empty datasets of type
+series and we will further manipulate them instead of individual maps. Usually, we create empty datasets of type
 strds (space-time raster dataset) and after that we register the raster files into the strds.
 With ``t.c.register`` we can combine these two steps and with the `flag -m`  we will visualize the temporal extents of
 the dataset (Note, that we use absolute time.)::

gscpy/ds1_download/ds1_download.py

@@ -129,14 +129,14 @@
 try:
     import grass.script as gs
 except ImportError:
-    raise ImportError("You must installed GRASS GIS to run this program.")
+    raise ImportError("You have to install GRASS GIS to run this program.")
 
 from sentinelsat.sentinel import SentinelAPI, read_geojson, geojson_to_wkt
 
 
 class S1Download(object):
     """
-    This module makes searching, downloading and retrieving the metadata of Sentinel satellite images from the
+    This module makes searching, downloading and retrieving metadata of Sentinel-1 satellite images from the
     Copernicus Open Access Hub easy.
 
     Parameters
@@ -195,12 +195,12 @@ class S1Download(object):
         >>> ["producttype", "polarisationmode", "sensoroperationalmode", "orbitnumber", "orbitdirection"]
 
     Print all Sentinel 1 data with product type GRD between 2015-01-02 and 2015-01-12::
-        $ ds1.download -p username=DALEK password=exterminate region=myGEoJsOnFile.geojson timestart=2015-01-02
+        $ ds1.download -p username=USER password=PASSWORD region=myGEoJsOnFile.geojson timestart=2015-01-02
         timeend=2015-01-12 outdir='home/usr/data' producttype=SLC
 
     Download the last query
     ::
-        $ ds1.download username=DALEK password=exterminate region=myGEoJsOnFile.geojson timestart=2015-01-02
+        $ ds1.download username=USER password=PASSWORD region=myGEoJsOnFile.geojson timestart=2015-01-02
         timeend=2015-01-12 outdir='home/usr/data' producttype=SLC
 
     Notes

gscpy/g_db/g_c_mapset.py

@@ -56,16 +56,16 @@
     import grass.script as gs
     from grass.exceptions import CalledModuleError
 except ImportError:
-    raise ImportError("You must installed GRASS GIS to run this program.")
+    raise ImportError("You have to install GRASS GIS to run this program.")
 
 
 class Mapset(object):
     """
     Create a mapset in a GRASS GIS Database if it is not existent. This will changes the current working MAPSET,
-    LOCATION, or GISDBASE. This is a fairly radical maneuver to run mid-session, take care when running the GUI
+    LOCATION, or GISDBASE. This is a fairly radical action to run mid-session, take care when running the GUI
     at the same time.
 
-    In GRASS GIS their is a similar function (`g.mapset`). This function shortens the flags and creates directly
+    In GRASS GIS there is a similar function (`g.mapset`). This function shortens the flags and creates directly
     a new mapset if it is not existent.
 
     Parameters

gscpy/g_db/g_database.py

@@ -73,7 +73,7 @@
 try:
     import grass.script as gs
 except ImportError:
-    raise ImportError("You must installed GRASS GIS to run this program.")
+    raise ImportError("You have to install GRASS GIS to run this program.")
 
 
 class Database(object):
@@ -134,8 +134,8 @@ class Database(object):
     -----
     It is mandatory that t_srs OR t_srs_file is set.
 
-    This class try to find `['grass70', 'grass71', 'grass72', 'grass73', 'grass74']` commands. The list can be
-    easily expand to another versions of GRASS GIS.
+    This class trys to find `['grass70', 'grass71', 'grass72', 'grass73', 'grass74']` commands. This list can
+    easily be extended for other versions of GRASS GIS.
 
     **Flags:**
         * l : Launch mapset with GRASS GIS.

gscpy/i_import/i_dr_import.py

@@ -111,19 +111,19 @@
     import grass.script as gs
     from grass.exceptions import CalledModuleError
 except ImportError:
-    raise ImportError("You must installed GRASS GIS to run this program.")
+    raise ImportError("You have to install GRASS GIS to run this program.")
 
 try:
     from osgeo import gdal, osr
 except ImportError as e:
     gs.fatal(_("Flag -r requires GDAL library: {}").format(e))
 
-    raise ImportError("You must installed GRASS GIS to run this program.")
+    raise ImportError("You have to install GRASS GIS to run this program.")
 
 
 class DirImport(object):
     """
-    Import data into a mapset from a file with considering a certain pattern.
+    Import data into a mapset from a file with considering certain patterns.
 
     Parameters
     ----------

gscpy/out_l_export/out_l_gdal.py

@@ -124,14 +124,14 @@
     import grass.script as gs
     from grass.exceptions import CalledModuleError
 except ImportError:
-    raise ImportError("You must installed GRASS GIS to run this program.")
+    raise ImportError("You have to install GRASS GIS to run this program.")
 
 try:
     from osgeo import gdal, osr
 except ImportError as e:
     gs.fatal(_("Flag -r requires GDAL library: {}").format(e))
 
-    raise ImportError("You must installed GRASS GIS to run this program.")
+    raise ImportError("You have to install GRASS GIS to run this program.")
 
 
 class OutLGdal(object):
@@ -147,7 +147,7 @@ class OutLGdal(object):
     pattern : str, optional
         The pattern of file names.
     exclude : str, optional
-        Which files or pattern should be excluded?
+        Which files or patterns should be excluded?
     mapset : str, optional
         Name of mapset to list (default: current search path); '*' for all mapsets in location.
     region : str, optional