[GRASS-SVN] r63403 - grass/trunk/lib/python/docs/src

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2014-12-06 10:57:32 -0800 (Sat, 06 Dec 2014)
New Revision: 63403

Modified:
   grass/trunk/lib/python/docs/src/script_intro.rst
Log:
pythonlib: basic description of standard options and flags for script doc

 * link to C API beacuse there is no other list of std options and flags
 * mention --script flag (but also source code since --script does not give standard options and flags)
 * mention also pylint besides pep8 (unfortunately, PEP8 does not allow #% but not mentioning that for now)


Modified: grass/trunk/lib/python/docs/src/script_intro.rst
===================================================================
--- grass/trunk/lib/python/docs/src/script_intro.rst	2014-12-06 18:27:46 UTC (rev 63402)
+++ grass/trunk/lib/python/docs/src/script_intro.rst	2014-12-06 18:57:32 UTC (rev 63403)
@@ -132,7 +132,28 @@
     if __name__ == "__main__":
         sys.exit(main())
 
+The options which has something like ``G_OPT_R_INPUT`` after the word
+``option`` are called standard options. Their list is accessible
+in GRASS GIS `C API documentation`_ of ``STD_OPT`` enum from ``gis.h`` file.
+Always use standard options if possible. They are not only easier to use
+but also ensure consistency across the modules and easier maintanenace
+in case of updates to the parameters parsing system.
+Typically, you change ``description`` (and/or ``label``), sometimes ``key``
+and ``answer``. There are also standard flags to be used
+with ``flag`` which work in the same way.
+
+The examples of syntax of options and flags (without the ``G_OPT...`` part)
+can be obtained from any GRASS module using special ``--script`` flag.
+Alternatively, you can use GRASS source code to look how different scripts
+actually define and use their parameters.
+
 Note that the previous code samples were missing some whitespace which
 Python PEP8 style guide requires but this last sample fulfills all the
 requirements. You should always use *pep8* tool to check your syntax and
-style or set your editor to do it for you.
+style or set your editor to do it for you. Note also that although
+a some mistakes in Python code can be discovered only when executing
+the code due to the dynamic nature of Python, there is a large number
+of tools such as *pep8* or *pylint* which can help you to identify problems
+in you Python code.
+
+.. _C API documentation: http://grass.osgeo.org/programming7/gis_8h.html