[GRASS-SVN] r61141 - in grass/trunk: include/Make lib/python lib/python/docs lib/python/docs/_static lib/python/docs/_templates lib/python/docs/src lib/python/pygrass man
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu Jul 3 07:56:26 PDT 2014
Author: lucadelu
Date: 2014-07-03 07:56:26 -0700 (Thu, 03 Jul 2014)
New Revision: 61141
Added:
grass/trunk/lib/python/docs/
grass/trunk/lib/python/docs/Makefile
grass/trunk/lib/python/docs/_build/
grass/trunk/lib/python/docs/_static/
grass/trunk/lib/python/docs/_static/pygrass.css
grass/trunk/lib/python/docs/_templates/
grass/trunk/lib/python/docs/_templates/layout.html.template
grass/trunk/lib/python/docs/_templates/oholosidebar.html
grass/trunk/lib/python/docs/conf.py
grass/trunk/lib/python/docs/make.bat
grass/trunk/lib/python/docs/src/
grass/trunk/lib/python/docs/src/index.rst
grass/trunk/lib/python/docs/src/pygrass_gis.rst
grass/trunk/lib/python/docs/src/pygrass_index.rst
grass/trunk/lib/python/docs/src/pygrass_messages.rst
grass/trunk/lib/python/docs/src/pygrass_modules.rst
grass/trunk/lib/python/docs/src/pygrass_raster.rst
grass/trunk/lib/python/docs/src/pygrass_vector.rst
Removed:
grass/trunk/lib/python/pygrass/docs/
Modified:
grass/trunk/include/Make/Sphinx.make
grass/trunk/man/Makefile
Log:
python documentation: start sphinx documentation for lib/python
Modified: grass/trunk/include/Make/Sphinx.make
===================================================================
--- grass/trunk/include/Make/Sphinx.make 2014-07-03 14:56:24 UTC (rev 61140)
+++ grass/trunk/include/Make/Sphinx.make 2014-07-03 14:56:26 UTC (rev 61141)
@@ -18,11 +18,17 @@
cleansphinx:
$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiclean
+ $(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs libpythonclean
sphinxdoc: checksphinx cleansphinx
$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiapidoc
$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguihtml
+ $(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
+ $(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonhtml
sphinxman:checksphinx cleansphinx
$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiapidoc
$(MAKE) -C $(MODULE_TOPDIR)/gui/wxpython/docs/wxgui_sphinx/ wxguiman
+ $(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonapidoc
+ $(MAKE) -C $(MODULE_TOPDIR)/lib/python/docs/ libpythonman
+
Added: grass/trunk/lib/python/docs/Makefile
===================================================================
--- grass/trunk/lib/python/docs/Makefile (rev 0)
+++ grass/trunk/lib/python/docs/Makefile 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,102 @@
+# Makefile for Sphinx documentation
+#
+MODULE_TOPDIR=../../..
+include $(MODULE_TOPDIR)/include/Make/Vars.make
+include $(MODULE_TOPDIR)/include/Make/Rules.make
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+ifneq (@(type sphinx-build2 > /dev/null),)
+SPHINXBUILD = sphinx-build2
+endif
+ifneq (@(type sphinx-build > /dev/null),)
+SPHINXBUILD = sphinx-build
+endif
+PAPER =
+BUILDDIR = _build
+BUILDDIR_HTML = $(HTMLDIR)/libpython
+
+MYGISBASE = $(GISBASE)
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . src/
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+.DEFAULT_GOAL := help
+
+libpythonhelp:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " libpythonhtml to make standalone HTML files"
+ @echo " libpythondirhtml to make HTML files named index.html in directories"
+ @echo " libpythonsinglehtml to make a single large HTML file"
+ @echo " libpythonepub to make an epub"
+ @echo " libpythonlatex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " libpythonlatexpdf to make LaTeX files and run them through pdflatex"
+ @echo " libpythonman to make manual pages"
+ @echo " libpythondoctest to run all doctests embedded in the documentation (if enabled)"
+
+libpythonclean:
+ -rm -rf $(BUILDDIR)/*
+ -rm -f _templates/layout.html
+ -rm -f src/ctypes*.rst
+ -rm -f src/imaging.rst
+ -rm -f src/pydispatch.rst
+ -rm -f src/pygrass.*rst
+ -rm -f src/script.rst
+ -rm -f src/temporal.rst
+
+libpythonapidoc:
+# $(call run_grass, sphinx-apidoc -T -f -o src/ ../ctypes/)
+ $(call run_grass,sphinx-apidoc -T -f -o src/ ../imaging/)
+ $(call run_grass,sphinx-apidoc -T -f -o src/ ../pydispatch/)
+ $(call run_grass,sphinx-apidoc -T -f -o src/ ../pygrass/)
+ $(call run_grass,sphinx-apidoc -T -f -o src/ ../script/)
+ $(call run_grass,sphinx-apidoc -T -f -o src/ ../temporal/)
+
+libpythonhtml:
+ $(call run_grass,$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
+
+libpythondirhtml:
+ $(call run_grass,$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
+
+libpythonsinglehtml:
+ $(call run_grass,$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR_HTML)"
+
+libpythonepub:
+ $(call run_grass,$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub)
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub/"
+
+libpythonlatex:
+ $(call run_grass,$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex)
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+libpythonlatexpdf:
+ $(call run_grass,$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex)
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/"
+
+libpythonman:
+ $(call run_grass,$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(MANDIR))
+ @echo
+ @echo "Build finished. The manual pages are in $(MANDIR)/"
+
+libpythondoctest:
+ $(call run_grass,$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest)
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
Property changes on: grass/trunk/lib/python/docs/Makefile
___________________________________________________________________
Added: svn:mime-type
+ text/x-makefile
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/_static/pygrass.css
===================================================================
--- grass/trunk/lib/python/docs/_static/pygrass.css (rev 0)
+++ grass/trunk/lib/python/docs/_static/pygrass.css 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,74 @@
+/* GRASS documentation site style sheet
+ *
+ * send improvements to GRASS Developers list
+ *
+ * (eg how to reach the same result on netscape, mozilla konqueror?)
+ *
+ * Fonts:
+ * http://www.w3.org/TR/REC-CSS2/fonts.html
+ * Tables:
+ * http://www.w3.org/TR/REC-CSS2/tables.html
+ */
+
+body{
+ background: white;
+ color: black;
+ font-family: arial,sans-serif;
+ width: 99%;
+ margin: 8px;
+}
+
+hr.header {
+ height: 3px;
+ color: gray;
+ background-color: gray;
+ width: 100%;
+}
+
+h1{
+ background-color: transparent;
+ color: rgb(25%, 60%, 25%);
+ font-family: arial,sans-serif;
+ font-weight: bold;
+ font-size: x-large;
+}
+
+h2{
+ background-color: transparent;
+ color: rgb(25%, 60%, 25%);
+ font-family: arial,sans-serif;
+ font-weight: bold;
+ font-size: large;
+}
+
+h3{
+ background-color: transparent;
+ color: rgb(25%, 60%, 25%);
+ font-family: arial,sans-serif;
+ font-weight: bold;
+ font-size: large;
+}
+
+h4{
+ background-color: transparent;
+ color: rgb(25%, 60%, 25%);
+ font-family: arial,sans-serif;
+ font-weight: bold;
+ font-size: medium;
+}
+
+table.border {
+ border-collapse:collapse;
+}
+
+table.border td {
+ border: 1px solid rgb(25%, 60%, 25%);
+}
+
+td {
+ padding: 5px;
+}
+
+div.related {
+ background-color: transparent;
+}
Added: grass/trunk/lib/python/docs/_templates/layout.html.template
===================================================================
--- grass/trunk/lib/python/docs/_templates/layout.html.template (rev 0)
+++ grass/trunk/lib/python/docs/_templates/layout.html.template 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,9 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+<link rel="stylesheet" href="{{ pathto('_static/pygrass.css', 1) }}" type="text/css" />
+{% endblock %}
+
+{% block header %}
+<img src="../grass_logo.png" alt="GRASS GIS logo">
+<hr class="header">
+{% endblock %}
\ No newline at end of file
Added: grass/trunk/lib/python/docs/_templates/oholosidebar.html
===================================================================
--- grass/trunk/lib/python/docs/_templates/oholosidebar.html (rev 0)
+++ grass/trunk/lib/python/docs/_templates/oholosidebar.html 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,9 @@
+<p width="210px">
+<iframe src='http://www.ohloh.net/p/3666/widgets/project_factoids_stats.html' scrolling='no' marginHeight=0 marginWidth=0 style='height: 160px; width: 210px; border: none;'></iframe>
+</p>
+<p width="210px">
+<iframe src='http://www.ohloh.net/p/3666/widgets/project_languages.html' scrolling='no' marginHeight=0 marginWidth=0 style='height: 160px; width: 210px; border: none;'></iframe>
+</p>
+<p width="210px">
+<iframe src='http://www.ohloh.net/p/3666/widgets/project_cocomo.html' scrolling='no' marginHeight=0 marginWidth=0 style='height: 160px; width: 210px; border: none;'></iframe>
+</p>
\ No newline at end of file
Property changes on: grass/trunk/lib/python/docs/_templates/oholosidebar.html
___________________________________________________________________
Added: svn:mime-type
+ text/html
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/conf.py
===================================================================
--- grass/trunk/lib/python/docs/conf.py (rev 0)
+++ grass/trunk/lib/python/docs/conf.py 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,364 @@
+# -*- coding: utf-8 -*-
+#
+# wxGUI documentation build configuration file, created by
+# sphinx-quickstart on Tue Jun 3 09:20:51 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+from datetime import date
+import string
+from shutil import copy
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+if not os.getenv('GISBASE'):
+ sys.exit("GISBASE not defined")
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'ctypes')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'imaging')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'pydispatch')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'pygrass')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'script')))
+sys.path.insert(0, os.path.abspath(os.path.join(os.environ['GISBASE'], 'etc', 'python', 'grass', 'temporal')))
+
+from grass.script import core
+
+footer_tmpl = string.Template(\
+r"""
+{% block footer %}<hr class="header">
+<p><a href="../index.html">Help Index</a> | <a href="../topics.html">Topics Index</a> | <a href="../keywords.html">Keywords Index</a> | <a href="../full_index.html">Full Index</a></p>
+<p>© 2003-${year} <a href="http://grass.osgeo.org">GRASS Development Team</a>, GRASS GIS ${grass_version} Reference Manual</p>
+{% endblock %}
+""")
+
+grass_version = core.version()['version']
+today = date.today()
+
+copy("_templates/layout.html.template", "_templates/layout.html")
+with open("_templates/layout.html", "a+b") as f:
+ f.write(footer_tmpl.substitute(grass_version=grass_version, year=today.year))
+ f.close()
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.todo',
+ 'sphinx.ext.coverage',
+ 'sphinx.ext.mathjax',
+ 'sphinx.ext.ifconfig',
+ 'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Python library documentation'
+copyright = u'2014, GRASS Development Team'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+#version = '0.1'
+# The full version, including alpha/beta/rc tags.
+#release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'python'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'traditional'
+
+# 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
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain 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']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+html_sidebars = {"**":["localtoc.html",'relations.html','searchbox.html']}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PythonLibdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+'papersize': 'a4paper',
+
+# The font size ('10pt', '11pt' or '12pt').
+'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ ('index', 'PythonLib.tex', u'Python Librart Documentation',
+ u'GRASS Development Team', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'PythonLib', u'Python Library Documentation',
+ [u'GRASS Development Team'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'PythonLib', u'Python Library Documentation',
+ u'GRASS Development Team', 'PythonLib', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'PythonLib'
+epub_author = u'GRASS Development Team'
+epub_publisher = u'GRASS Development Team'
+epub_copyright = u'2014, GRASS Development Team'
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = u'wxGUI'
+
+# The HTML theme for the epub output. Since the default themes are not optimized
+# for small screen space, using the same theme for HTML and epub output is
+# usually not wise. This defaults to 'epub', a theme designed to save visual
+# space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the PIL.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
Property changes on: grass/trunk/lib/python/docs/conf.py
___________________________________________________________________
Added: svn:mime-type
+ text/x-python
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/make.bat
===================================================================
--- grass/trunk/lib/python/docs/make.bat (rev 0)
+++ grass/trunk/lib/python/docs/make.bat 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,242 @@
+ at ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. xml to make Docutils-native XML files
+ echo. pseudoxml to make pseudoxml-XML files for display purposes
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\wxGUI.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\wxGUI.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdf" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdfja" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf-ja
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+if "%1" == "xml" (
+ %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The XML files are in %BUILDDIR%/xml.
+ goto end
+)
+
+if "%1" == "pseudoxml" (
+ %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+ goto end
+)
+
+:end
Property changes on: grass/trunk/lib/python/docs/make.bat
___________________________________________________________________
Added: svn:mime-type
+ text/x-bat
Added: svn:eol-style
+ CRLF
Added: grass/trunk/lib/python/docs/src/index.rst
===================================================================
--- grass/trunk/lib/python/docs/src/index.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/index.rst 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,14 @@
+GRASS GIS Python library documentation
+==========================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ script
+ pygrass_index
+ temporal
+ imaging
+ pydispatch
+
Property changes on: grass/trunk/lib/python/docs/src/index.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/src/pygrass_gis.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_gis.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/pygrass_gis.rst 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,17 @@
+.. _GRASSdatabase-label:
+
+GRASS database management
+===============================
+
+These classes are used to manage the infrastructure
+of GRASS database: Gisdbase, Location and Mapset
+
+
+.. _Region-label:
+
+Region management
+======================
+
+The Region class it is useful to obtain information
+about the computational region and to change it.
+
Property changes on: grass/trunk/lib/python/docs/src/pygrass_gis.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/src/pygrass_index.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_index.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/pygrass_index.rst 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,57 @@
+PyGRASS documentation
+===================================
+
+Python is a programming language which is more powerful than shell
+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
+functionality, as well as to vector and raster data. For details,
+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
+natural for the user.
+
+Background: In 2006, GRASS GIS developers started to adopt Python
+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).
+
+
+Read more about how to work with ``pygrass`` in this documentation.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ pygrass_gis
+ pygrass_raster
+ pygrass_vector
+ pygrass_modules
+ pygrass_messages
+ pygrass
+
+
+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>`_
+
+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
+ ==================
+
+ * :ref:`genindex`
+ * :ref:`modindex`
+ * :ref:`search`
+
Property changes on: grass/trunk/lib/python/docs/src/pygrass_index.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/src/pygrass_messages.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_messages.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/pygrass_messages.rst 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,6 @@
+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>`_.
+
Property changes on: grass/trunk/lib/python/docs/src/pygrass_messages.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/src/pygrass_modules.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_modules.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/pygrass_modules.rst 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,208 @@
+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). ::
+
+ >>> from pygrass.modules import Module
+ >>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
+ ... slope='slp', aspect='asp',
+ ... format='percent', overwrite=True)
+
+
+It is possible to create a run-able module object and run it later (this
+is also needed for registering GRASS GIS commands with more than one dot
+in their name, e.g. r.slope.aspect):
+
+ >>> slope_aspect = Module("r.slope.aspect", elevation='elevation',
+ ... slope='slp', aspect='asp',
+ ... format='percent', overwrite=True, run_=False)
+
+Then we can run the module with: ::
+
+ >>> slope_aspect()
+
+or using the run method: ::
+
+ >>> slope_aspect.run()
+
+
+It is possible to initialize a module, and give the parameters later: ::
+
+ >>> slope_aspect = Module("r.slope.aspect")
+ >>> slope_aspect(elevation='elevation', slope='slp', aspect='asp',
+ ... format='percent', overwrite=True)
+
+
+Create the module object input step by step and run later: ::
+
+ >>> slope_aspect = Module("r.slope.aspect")
+ >>> slope_aspect.inputs['elevation']
+ Parameter <elevation> (required:yes, type:raster, multiple:no)
+ >>> slope_aspect.inputs["elevation"].value = "elevation"
+ >>> slope_aspect.inputs["format"]
+ Parameter <format> (required:no, type:string, multiple:no)
+ >>> print slope_aspect.inputs["format"].__doc__
+ format: 'degrees', optional, string
+ Format for reporting the slope
+ Values: 'degrees', 'percent'
+ >>> slope_aspect.inputs["format"].value = 'percents'
+ Traceback (most recent call last):
+ ...
+ ValueError: The Parameter <format>, must be one of: ['degrees', 'percent']
+ >>> slope_aspect.inputs["format"].value = 'percent'
+ >>> slope_aspect.flags = "g"
+ Traceback (most recent call last):
+ ...
+ ValueError: Flag not valid, valid flag are: ['a']
+ >>> slope_aspect.flags = "a"
+ >>> slope_aspect.flags_dict['overwrite']
+ Flag <overwrite> (Allow output files to overwrite existing files)
+ >>> slope_aspect.flags_dict['overwrite'].value = True
+ >>> slope_aspect()
+
+
+
+It is possible to access the module descriptions (name, one line description,
+keywords, label) with:
+
+ >>> slope_aspect.name
+ 'r.slope.aspect'
+ >>> slope_aspect.description
+ 'Aspect is calculated counterclockwise from east.'
+ >>> slope_aspect.keywords
+ 'raster, terrain'
+ >>> slope_aspect.label
+ 'Generates raster maps of slope, aspect, curvatures and partial derivatives from a elevation raster map.'
+
+and get the module documentation with: ::
+
+ >>> print slope_aspect.__doc__
+ r.slope.aspect(elevation=elevation, slope=None, aspect=None
+ format=percent, prec=None, pcurv=None
+ tcurv=None, dx=None, dy=None
+ dxx=None, dyy=None, dxy=None
+ zfactor=None, min_slp_allowed=None)
+ <BLANKLINE>
+ Parameters
+ ----------
+ <BLANKLINE>
+ <BLANKLINE>
+ elevation: required, string
+ Name of input elevation raster map
+ slope: optional, string
+ Name for output slope raster map
+ aspect: optional, string
+ Name for output aspect raster map
+ format: 'degrees', optional, string
+ Format for reporting the slope
+ Values: 'degrees', 'percent'
+ prec: 'float', optional, string
+ Type of output aspect and slope maps
+ Values: 'default', 'double', 'float', 'int'
+ pcurv: optional, string
+ Name for output profile curvature raster map
+ tcurv: optional, string
+ Name for output tangential curvature raster map
+ dx: optional, string
+ Name for output first order partial derivative dx (E-W slope) raster map
+ dy: optional, string
+ Name for output first order partial derivative dy (N-S slope) raster map
+ dxx: optional, string
+ Name for output second order partial derivative dxx raster map
+ dyy: optional, string
+ Name for output second order partial derivative dyy raster map
+ dxy: optional, string
+ Name for output second order partial derivative dxy raster map
+ zfactor: 1.0, optional, float
+ Multiplicative factor to convert elevation units to meters
+ min_slp_allowed: optional, float
+ Minimum slope val. (in percent) for which aspect is computed
+ <BLANKLINE>
+ Flags
+ ------
+ <BLANKLINE>
+ a: None
+ Do not align the current region to the elevation layer
+ overwrite: None
+ Allow output files to overwrite existing files
+ verbose: None
+ Verbose module output
+ quiet: None
+ Quiet module output
+
+
+
+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))])
+
+To get information for each parameter: ::
+
+ >>> slope_aspect.inputs["elevation"].description
+ 'Name of input elevation raster map'
+ >>> slope_aspect.inputs["elevation"].type
+ 'raster'
+ >>> slope_aspect.inputs["elevation"].typedesc
+ 'string'
+ >>> slope_aspect.inputs["elevation"].multiple
+ False
+ >>> slope_aspect.inputs["elevation"].required
+ True
+
+Or get a small documentation for each parameter with:
+
+ >>> print slope_aspect.inputs["elevation"].__doc__
+ elevation: required, string
+ Name of input elevation raster map
+
+
+User or developer can check which parameters have been set, with: ::
+
+ if slope_aspect.outputs['aspect'].value == None:
+ print "Aspect is not computed"
+
+
+After we set the parameters and run the module, the execution of the module
+instantiate a popen attribute to the class. The `Popen`_ class allow user
+to kill/wait/ the process. ::
+
+ >>> slope_aspect = Module('r.slope.aspect')
+ >>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=False)
+ >>> slope_aspect.popen.wait() # *.kill(), *.terminate()
+ 0
+ >>> out, err = slope_aspect.popen.communicate()
+ >>> print err #doctest: +NORMALIZE_WHITESPACE
+ 100%
+ Aspect raster map <asp> complete
+ Slope raster map <slp> complete
+ <BLANKLINE>
+
+On the above example we use a new parameter `finish_`, if is set to True, the
+run method, automatically store the stdout and stderr to stdout and stderr
+attributes of the class: ::
+
+ >>> slope_aspect = Module('r.slope.aspect')
+ >>> slope_aspect(elevation='elevation', slope='slp', aspect='asp', overwrite=True, finish_=True)
+ >>> print slope_aspect.stderr #doctest: +NORMALIZE_WHITESPACE
+ 100%
+ Aspect raster map <asp> complete
+ Slope raster map <slp> complete
+ <BLANKLINE>
+
+Another example of use: ::
+
+ >>> info = Module("r.info", map="elevation", flags="r", finish_=True)
+ >>> from pygrass.modules import stdout2dict
+ >>> stdout2dict(info.stdout)
+ {'max': '156.3299', 'min': '55.57879'}
+ >>> info = Module("r.info", map="elevation", flags="r", finish_=False)
+ >>> category = Module("r.category", map="elevation",
+ ... stdin_=info.popen.stdout, finish_=True)
+
+
+
+.. _Popen: http://docs.python.org/library/subprocess.html#Popen
Property changes on: grass/trunk/lib/python/docs/src/pygrass_modules.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/src/pygrass_raster.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_raster.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/pygrass_raster.rst 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,254 @@
+.. _raster-label:
+
+Introduction to Raster classes
+==============================
+
+Details about the architecture can be found in the `GRASS GIS 7 Programmer's Manual: GRASS Raster Library <http://grass.osgeo.org/programming7/rasterlib.html>`_
+
+PyGRASS uses 4 different Raster classes, that respect the 4 different approaches
+of GRASS-C API.
+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` and :ref:`RasterNumpy-label`
+are tile cached for reading and writing therefore a randomly access is possible.
+Hence RasterRow and RasterRowIO should be used in case for fast (cached)
+row read access and RasterRow for fast sequential writing.
+Segment and Numpy should be used for random access, but Numpy only for files
+not larger than 2GB.
+
+
+========================== ======================= ======== ============
+Class Name C library Read Write
+========================== ======================= ======== ============
+:ref:`RasterRow-label` `Raster library`_ randomly sequentially
+:ref:`RasterRowIO-label` `RowIO library`_ cached no
+:ref:`RasterSegment-label` `Segmentation library`_ cached randomly
+:ref:`RasterNumpy-label` `numpy.memmap`_ cached randomly
+========================== ======================= ======== ============
+
+
+All these classes share common methods and attributes, necessary to address
+common tasks as rename, remove, open, close, exist, is_open.
+In the next examples we instantiate a RasterRow object. ::
+
+ >>> from pygrass import raster
+ >>> elev = raster.RasterRow('elevation')
+ >>> elev.name
+ 'elevation'
+ >>> print(elev)
+ elevation at PERMANENT
+ >>> elev.exist()
+ True
+ >>> elev.is_open()
+ False
+ >>> new = raster.RasterRow('new')
+ >>> new.exist()
+ False
+ >>> new.is_open()
+ False
+
+
+We can rename the map: ::
+
+ >>> # setting the attribute
+ >>> new.name = 'new_map'
+ >>> print(new)
+ new_map
+ >>> # or using the rename methods
+ >>> new.rename('new')
+ >>> print(new)
+ new
+
+.. _RasterRow-label:
+
+RastRow
+-------
+
+PyGrass allow user to open the maps, in read and write mode,
+row by row using the `Raster library`_, there is not support to read and write
+to the same map at the same time, for this functionality, please see the
+:ref:`RasterSegment-label` and :ref:`RasterNumpy-label` classes.
+The RasterRow class allow to read in a randomly order the row from a map, but
+it is only possible to write the map using only a sequence order, therefore every
+time you are writing a new map, the row is add to the file as the last row. ::
+
+ >>> raster = reload(raster)
+ >>> elev = raster.RasterRow('elevation')
+ >>> # the cols attribute is set from the current region only when the map is open
+ >>> elev.cols
+ >>> elev.open()
+ >>> elev.is_open()
+ True
+ >>> elev.cols
+ 1500
+ >>> # we can read the elevation map, row by row
+ >>> for row in elev[:5]: print(row[:3])
+ [ 141.99613953 141.27848816 141.37904358]
+ [ 142.90461731 142.39450073 142.68611145]
+ [ 143.81854248 143.54707336 143.83972168]
+ [ 144.56524658 144.58493042 144.86477661]
+ [ 144.99488831 145.22894287 145.57142639]
+ >>> # we can open a new map in write mode
+ >>> new = raster.RasterRow('new')
+ >>> new.open('w', 'CELL')
+ >>> # for each elev row we can perform computation, and write the result into
+ >>> # the new map
+ >>> for row in elev:
+ ... new.put_row(row < 144)
+ ...
+ >>> # close the maps
+ >>> new.close()
+ >>> elev.close()
+ >>> # check if the map exist
+ >>> new.exist()
+ True
+ >>> # we can open the map in read mode
+ >>> new.open('r')
+ >>> for row in new[:5]: print(row[:3])
+ [1 1 1]
+ [1 1 1]
+ [1 1 1]
+ [0 0 0]
+ [0 0 0]
+ >>> new.close()
+ >>> new.remove()
+ >>> new.exist()
+ False
+
+
+.. _RasterRowIO-label:
+
+RasterRowIO
+-----------
+
+The RasterRowIO class use the grass `RowIO library`_, and implement a row
+cache. The RasterRowIO class support only reading the raster, because the
+raster rows can only be written in sequential order, writing by row id is not
+supported by design. Hence, we should use the rowio lib only for caching rows
+for reading and use the default row write access as in the RasterRow class. ::
+
+ >>> raster = reload(raster)
+ >>> elev = raster.RasterRowIO('elevation')
+ >>> elev.open('r')
+ >>> for row in elev[:5]: print(row[:3])
+ [ 141.99613953 141.27848816 141.37904358]
+ [ 142.90461731 142.39450073 142.68611145]
+ [ 143.81854248 143.54707336 143.83972168]
+ [ 144.56524658 144.58493042 144.86477661]
+ [ 144.99488831 145.22894287 145.57142639]
+ >>> elev.close()
+
+
+.. _RasterSegment-label:
+
+RastSegment
+-----------
+
+The RasterSegment class use the grass `Segmentation library`_, it work dividing
+the raster map into small different files, that grass read load into the memory
+and write to the hardisk.
+The segment library allow to open a map in a read-write mode. ::
+
+ >>> raster = reload(raster)
+ >>> elev = raster.RasterSegment('elevation')
+ >>> elev.open()
+ >>> for row in elev[:5]: print(row[:3])
+ [ 141.99613953 141.27848816 141.37904358]
+ [ 142.90461731 142.39450073 142.68611145]
+ [ 143.81854248 143.54707336 143.83972168]
+ [ 144.56524658 144.58493042 144.86477661]
+ [ 144.99488831 145.22894287 145.57142639]
+ >>> new = raster.RasterSegment('new')
+ >>> new.open('w', 'CELL')
+ >>> for irow in xrange(elev.rows):
+ ... new[irow] = elev[irow] < 144
+ ...
+ >>> for row in new[:5]: print(row[:3])
+ [1 1 1]
+ [1 1 1]
+ [1 1 1]
+ [0 0 0]
+ [0 0 0]
+
+The RasterSegment class define two methods to read and write the map:
+
+ * ``get_row`` that return the buffer object with the row that call the
+ C function ``segment_get_row``. ::
+
+ >>> # call explicity the method
+ >>> elev_row0 = elev.get_row(0)
+ >>> # call implicity the method
+ >>> elev_row0 = elev[0]
+
+ * ``get`` that return the value of the call map that call the
+ C function ``segment_get``. ::
+
+ >>> # call explicity the method
+ >>> elev_val_0_0 = elev.get(0, 0)
+ >>> # call implicity the method
+ >>> elev_val_0_0 = elev[0, 0]
+
+Similarly to write the map, with ``put_row``, to write a row and with ``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
+ >>> elev[0, 0] == elev[0][0]
+ True
+ >>> # write a new value to a cell,
+ >>> new[0, 0] = 10
+ >>> new[0, 0]
+ 10
+ >>> new.close()
+ >>> new.exist()
+ True
+ >>> new.remove()
+ >>> elev.close()
+ >>> elev.remove()
+
+
+.. _RasterNumpy-label:
+
+RasterNumpy
+-----------
+
+The RasterNumpy class, is based on the `numpy.memmap`_ class If you open an
+existing map, the map will be copied on a binary format, and read to avoid
+to load all the map in memory. ::
+
+ >>> raster = reload(raster)
+ >>> elev = raster.RasterNumpy('elevation', 'PERMANENT')
+ >>> elev.open('r')
+ >>> # in this case RasterNumpy is an extention of the numpy class
+ >>> # therefore you may use all the fancy things of numpy.
+ >>> elev[:5, :3]
+ RasterNumpy([[ 141.99613953, 141.27848816, 141.37904358],
+ [ 142.90461731, 142.39450073, 142.68611145],
+ [ 143.81854248, 143.54707336, 143.83972168],
+ [ 144.56524658, 144.58493042, 144.86477661],
+ [ 144.99488831, 145.22894287, 145.57142639]], dtype=float32)
+ >>> el = elev < 144
+ >>> el[:5, :3]
+ RasterNumpy([[1, 1, 1],
+ [1, 1, 1],
+ [1, 1, 1],
+ [0, 0, 0],
+ [0, 0, 0]], dtype=int32)
+ >>> el.name == None
+ True
+ >>> # give a name to the new map
+ >>> el.name = 'new'
+ >>> el.exist()
+ False
+ >>> el.close()
+ >>> el.exist()
+ True
+ >>> el.remove()
+
+
+.. _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
+.. _numpy.memmap: http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html
+
Property changes on: grass/trunk/lib/python/docs/src/pygrass_raster.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Added: grass/trunk/lib/python/docs/src/pygrass_vector.rst
===================================================================
--- grass/trunk/lib/python/docs/src/pygrass_vector.rst (rev 0)
+++ grass/trunk/lib/python/docs/src/pygrass_vector.rst 2014-07-03 14:56:26 UTC (rev 61141)
@@ -0,0 +1,118 @@
+.. _vector-label:
+
+Introduction to Vector classes
+==============================
+
+Details about the architecture can be found in the `GRASS GIS 7 Programmer's Manual: GRASS Vector Library <http://grass.osgeo.org/programming7/vectorlib.html>`_
+
+
+Instantiation and basic interaction. ::
+
+ >>> from pygrass.vector import VectTopo
+ >>> municip = VectTopo('boundary_municp_sqlite')
+ >>> municip.is_open()
+ False
+ >>> municip.mapset
+ ''
+ >>> municip.exist() # check if exist, and if True set mapset
+ True
+ >>> municip.mapset
+ 'user1'
+
+
+
+Open the map with topology: ::
+
+ >>> municip.open()
+
+ get the number of primitive:
+ >>> municip.num_primitive_of('line')
+ 0
+ >>> municip.num_primitive_of('centroid')
+ 3579
+ >>> municip.num_primitive_of('boundary')
+ 5128
+
+
+
+ask for other feature in the vector map: ::
+
+ >>> municip.number_of("areas")
+ 3579
+ >>> municip.number_of("islands")
+ 2629
+ >>> municip.number_of("holes")
+ 0
+ >>> municip.number_of("lines")
+ 8707
+ >>> municip.number_of("nodes")
+ 4178
+ >>> municip.number_of("pizza") # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
+ Traceback (most recent call last):
+ ...
+ ValueError: vtype not supported, use one of: 'areas', ..., 'volumes'
+
+
+Suppose that we want to select all and only the areas that have an
+area bigger than 10000m2: ::
+
+ >>> big = [area for area in municip.viter('areas')
+ ... if area.alive() and area.area >= 10000]
+
+it's pretty easy, isn't it?!? :-)
+
+the method "viter" return an iterator object of the vector features,
+in this way no memory is wasted... User can choose on which
+vector features want to iterate...
+
+
+then you can go on with python stuff like, sort by area dimension: ::
+
+ >>> from operator import methodcaller as method
+ >>> big.sort(key = method('area'), reverse = True) # sort the list
+ >>> for area in big[:3]:
+ ... print area, area.area()
+ Area(3102) 697521857.848
+ 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)
+ >>> for area in big[:3]:
+ ... print area, area.isles.__len__()
+ ...
+ Area(2682) 68
+ Area(2753) 45
+ Area(872) 42
+
+
+or you may have only the list of the areas that contain isles inside, with: ::
+
+ >>> area_with_isles = [area for area in big if area.isles]
+ >>> area_with_isles # doctest: +ELLIPSIS
+ [Area(...), ..., Area(...)]
+
+
+
+Of course is still possible work only with a specific area, with: ::
+
+ >>> from pygrass.vector.geometry import Area
+ >>> area = Area(v_id=1859, c_mapinfo=municip.c_mapinfo)
+ >>> area.area()
+ 39486.05401495844
+ >>> area.bbox() # north, south, east, west
+ Bbox(175711.718494, 175393.514494, 460344.093986, 460115.281986)
+ >>> area.isles
+ Isles([])
+
+
+Now, find an area with an island inside... ::
+
+ >>> area = Area(v_id=2972, c_mapinfo=municip.c_mapinfo)
+ >>> area.isles # doctest: +ELLIPSIS
+ Isles([Isle(1538), Isle(1542), Isle(1543), ..., Isle(2571)])
+ >>> isle = area.isles[0]
+ >>> isle.bbox()
+ Bbox(199947.296494, 199280.969494, 754920.623987, 754351.812986)
Property changes on: grass/trunk/lib/python/docs/src/pygrass_vector.rst
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
Modified: grass/trunk/man/Makefile
===================================================================
--- grass/trunk/man/Makefile 2014-07-03 14:56:24 UTC (rev 61140)
+++ grass/trunk/man/Makefile 2014-07-03 14:56:26 UTC (rev 61141)
@@ -41,13 +41,11 @@
$(MAKE) $(INDICES)
$(call build,check)
$(MAKE) manpages
- @(type $(SPHINXBUILD) > /dev/null && $(call run_pygrass_html) || (echo "WARNING: pygrass HTML documentation not compiled because 'sphinx-build' software not installed (get from http://www.sphinx.org)") ; exit 0)
# This must be a separate target so that evaluation of $(MANPAGES)
# is delayed until the indices have been generated
manpages:
$(MAKE) $(MANPAGES)
- @(type $(SPHINXBUILD) > /dev/null && $(call run_pygrass_man) || (echo "WARNING: pygrass MAN documentation not compiled because 'sphinx-build' software not installed (get from http://www.sphinx.org)") ; exit 0)
.PHONY: manpages
@@ -69,14 +67,6 @@
$(PYTHON) ./build_keywords.py $(HTMLDIR)
endef
-define run_pygrass_html
-$(MAKE) -C ../lib/python/pygrass/docs/ html
-endef
-
-define run_pygrass_man
-$(MAKE) -C ../lib/python/pygrass/docs/ man
-endef
-
$(HTMLDIR)/topics.html: $(ALL_HTML)
$(call build_topics)
touch $@
More information about the grass-commit
mailing list