wxGUI/toolboxes: documentation converted from Doxygen to Sphinx (https://trac.osgeo.org/grass/ticket/2435)

Documentation introduced in https://trac.osgeo.org/grass/changeset/56035 as dox and removed in r62097.

This commit also removes the standalone Sphix documenation added
in https://trac.osgeo.org/grass/changeset/62138 whcih was created by conversion of Doxygen generated HTML
to ODF and to Sphinx.


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

gui/wxpython/docs/wxgui_sphinx/conf.py

@@ -58,6 +58,7 @@ extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinx.ext.graphviz',
 ]
 todo_include_todos = True
 # Add any paths that contain templates here, relative to this directory.

gui/wxpython/docs/wxgui_sphinx/src/index.rst

@@ -1,16 +1,21 @@
-.. wxGUI documentation master file, created by
-   sphinx-quickstart on Tue Jun  3 09:20:51 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 wxGUI documentation
-=================================
+===================
+
+This is documentation of GRASS wxGUI which is a GRASS GIS GUI
+implemented in Python and `wxPython <http://wxpython.org>`_.
+The documentation is intended to be
+used by GRASS GIS developers only because the documented API is
+not guaranteed to be stable. If you are thinking about doing some
+development using this API, please contact other developers at
+`grass-dev <http://lists.osgeo.org/listinfo/grass-dev>`_ mailing list.
+
 
 .. toctree::
   :maxdepth: 2
 
   wxgui_libraries
   wxgui_tools
+  wxgui_toolboxes
 
 
 Indices and tables

gui/wxpython/docs/wxgui_sphinx/src/wxgui_toolboxes.rst

@@ -0,0 +1,402 @@
+WxGUI Toolboxes
+===============
+
+Introduction
+------------
+
+wxGUI toolboxes enables GUI customization and organization of menu (and other
+views) according to user needs.
+
+XML files are used for code generation and in case of toolboxes enables
+wxGUI (menu) customization.
+
+Currently, all the files described here are related to the menus which are
+generated from these files. The most of the files described here are
+the part of implementation of toolboxes in wxGUI.
+
+Each XML file has a DTD file which can by used for validation. XSD files are
+not provided (but this can change in the future). Some file types can occur
+multiple times, some occur only once.
+
+Note that in XML context, the term *tag* partially overlaps with the term
+*element*. Element emphasizes the XML structure, XML object model and
+content of these objects. Tag emphasizes the markup and the name of the element.
+
+
+Files overview
+--------------
+
+Files related to toolboxes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GRASS source code contains these XML files:
+
+* ``gui/wxpython/xml/main_menu.xml``
+* ``gui/wxpython/xml/toolboxes.xml``
+* ``gui/wxpython/xml/wxgui_items.xml``
+
+
+GRASS distribution contains these XML files:
+
+* ``etc/gui/wxpython/xml/main_menu.xml``
+* ``etc/gui/wxpython/xml/toolboxes.xml``
+* ``etc/gui/wxpython/xml/wxgui_items.xml``
+* ``etc/gui/wxpython/xml/module_items.xml`` (generated during compilation)
+* ``etc/gui/wxpython/xml/menudata.xml`` (generated during compilation)
+
+
+GRASS directory (``.grass7``) in user home directory
+(i.e., ``$HOME`` on Unix) contains these XML files:
+
+* ``toolboxes/main_menu.xml`` (created by user)
+* ``toolboxes/toolboxes.xml`` (created by user)
+* ``toolboxes/menudata.xml`` (generated on wxGUI startup)
+
+
+.. graphviz::
+
+    digraph toolboxes {
+        graph [rankdir="LR"];
+        node [shape="record", style="rounded"];
+
+        menudata [label="menudata.xml in distribution", shape="note", URL="#menudata-file"];
+        umenudata [label="menudata.xml in user home", shape="note", URL="#menudata-file"];
+        toolboxes [label="toolboxes.xml in distribution", shape="note", URL="#toolboxes-file"];
+        utoolboxes [label="toolboxes.xml in user home", shape="note", URL="#toolboxes-file"];
+        main_menu [label="main_menu.xml in distribution", shape="note", URL="#main-menu-file"];
+        umain_menu [label="main_menu.xml in user home", shape="note", URL="#main-menu-file"];
+
+        wxgui_items [label="wxgui_items.xml in distribution", shape="note", URL="#wxgui-items-file"];
+        module_items [label="module_items.xml in distribution", shape="note", URL="#module-items-file"];
+
+        menustrings [label="menustrings.py\n(used for translations)", shape="note"];
+
+        module_items -> menudata;
+        wxgui_items -> menudata;
+        main_menu -> menudata;
+        toolboxes -> menudata;
+
+        module_items -> umenudata;
+        wxgui_items -> umenudata;
+        toolboxes -> umenudata;
+        main_menu -> umenudata;
+        umain_menu -> umenudata;
+        utoolboxes -> umenudata;
+
+        menudata -> menustrings;
+
+        // guimenu [label="Main menu in wxGUI", shape="box3d"];
+        // menustrings -> guimenu;
+        // menudata -> guimenu;
+        // umenudata -> guimenu;
+    }
+
+
+Other files
+^^^^^^^^^^^
+
+GRASS source code contains these XML files:
+
+* ``gui/wxpython/xml/menudata_gmodeler.xml``
+* ``gui/wxpython/xml/menudata_psmap.xml``
+
+In GRASS distribution these XML files are in the ``etc/gui/wxpython/xml``
+directory.
+
+
+Generation of files and menu
+----------------------------
+
+As noted in the section \ref toolboxesFilesOverview, there are files in the
+GRASS distribution and in the user home directory (particularly in
+``.grass7/tooboxes`` subdirectory).
+
+When user doesn't have any ``toolboxes.xml`` or ``main_menu.xml`` files in the
+home directory, file ``menudata.xml`` included in the distribution is used to
+build a menu.
+
+When ``toolboxes.xml`` or ``main_menu.xml`` file (in user home directory) is newer
+than ``menudata.xml`` in user home directory or ``menudata.xml`` does not exists
+in user home directory, the ``menudata.xml`` is generated when GUI starts.
+
+When ``menudata.xml`` in user home directory is fresh enough,
+it is used to create a menu.
+
+When ``toolboxes.xml`` or ``main_menu.xml`` file is not in user home directory
+but ``menudata.xml`` is, the file is re-generated (each time the GUI starts).
+So, if you just have your own ``main_menu.xml``, it is better to create also
+a ``toolboxes.xml`` file with no toolboxes (note that you still need to create
+a valid XML toolbox file).
+Similarly, if you have only the ``toolboxes.xml`` file it
+is better to copy the ``main_menu.xml`` file from distribution into your home
+directory.
+
+When reading the main_menu file, user toolboxes are expanded first and then
+toolboxes from distribution are expanded.
+
+
+Toolboxes file
+--------------
+
+This file contains definition of toolboxes. A toolbox contains references
+(links) to other items, namely ``<module-items>``, ``<wxgui-items>``
+and other toolboxes using tag ``<subtoolbox>``. Tag ``<separator>`` is
+used when the view supports some kind of visual separators to group parts
+of the toolbox (or menu).
+
+Items are referenced using ``name`` attribute. In case of ``<module-items>``,
+``<wxgui-items>`` also subelements can be added to create new items or to
+replace subelements values from item definition.
+
+.. graphviz::
+
+    graph toolboxes {
+        graph [rankdir="LR"];
+        node [shape="record", style="rounded"];
+
+        // ∞ causes Doxygen warning but it's harmless for dot and html output
+
+        toolboxes -- toolbox [label="1..∞"];
+
+        toolbox -- label;
+        toolbox -- items [label="1..∞"];
+
+        items -- "module-item" [label="0..1"];
+        items -- "wxgui-item" [label="0..1"];
+        items -- subtoolbox [label="0..1"];
+        items -- separator [label="0..1"];
+
+        milabel [label="label"];
+
+        "module-item" -- milabel;
+        "module-item" -- module [label="0..1"];
+        "module-item" -- description [label="0..1"];
+        "module-item" -- keywords [label="0..1"];
+
+        wilabel [label="label"];
+        widescription [label="description"];
+        wikeywords [label="keywords"];
+
+        "wxgui-item" -- wilabel [label="0..1"];
+        "wxgui-item" -- handler [label="0..1"];
+        "wxgui-item" -- "related-module" [label="0..1"];
+        "wxgui-item" -- command [label="0..1"];
+        "wxgui-item" -- widescription [label="0..1"];
+        "wxgui-item" -- wikeywords [label="0..1"];
+        "wxgui-item" -- shortcut [label="0..1"];
+        "wxgui-item" -- "wx-id" [label="0..1"];
+    }
+
+
+
+Main menu file
+--------------
+
+File has a layout similar to the \ref toolboxesFile but contains only one
+toolbox (``<toolbox>``) which can contain only subtoolboxes
+(``<subtoolbox>`` elements) and one special
+element ``<user-toolboxes-list>`` which will be replaced by a menu with the list
+of toolboxes in the user toolbox file.
+
+
+Modules items file
+------------------
+
+The file contains information obtained from modules' interface descriptions.
+The structure of one ``module-item`` is the same as in the \ref toolboxesFile
+but some subelements are mandatory.
+
+File contained in distribution is generated during compilation from available
+modules using the script ``gui/wxpython/tools/build_modules_xml.py``.
+
+Element ``<module>`` is the name of the executable, e.g. ``r.info``.
+
+Element ``<label>`` is currently not present. It represents the short label in
+menu and it is added in toolboxes.
+
+Element ``<description>`` is created from module's description (or if
+it exists, label concatenated with description).
+
+Element ``<keywords>`` is created from module's keywords.
+
+
+wxGUI items file
+----------------
+
+The file contains definitions of wxGUI actions which can be accessed for
+example, from menu.
+The structure of one ``wxgui-item`` is the same as in \ref toolboxesFile
+but some subelements are mandatory.
+
+
+Menudata file
+-------------
+
+Historically, menudata.xml file was in the source codes and was partially
+maintained by the script ``gui/wxpython/tools/update_menudata.py``
+which updated the description and keywords (based on module's
+label or description, and keywords).
+Other items (menu structure, menu item labels and non-module only items) were
+edited in the menudata.xml file directly.
+
+Currently, the file is generated during compilation or at startup. It serves
+as an intermediate layer between all toolboxes XMLs and GUI menu tree
+generation.
+
+
+How to write a custom toolbox
+-----------------------------
+
+To create a new toolbox use ``<toolbox>`` tag:
+
+.. code-block:: xml
+
+    <toolbox name="MyRaster">
+      <label>My &amp;raster</label>
+      <items>
+        <!-- ... -->
+      </items>
+    </toolbox>
+
+To create a new item which represents a module use ``<module-item>`` tag:
+
+.. code-block:: xml
+
+    <module-item name="r.buffer">
+      <label>Buffer rasters</label>
+    </module-item>
+
+This works for modules contained in distribution. For modules from addons or
+some your modules which are on path use ``<module-item>`` tag together with
+``<module>`` tag:
+
+.. code-block:: xml
+
+    <module-item name="r.agent">
+      <label>Buffer rasters</label>
+      <module>r.agent</module>
+    </module-item>
+
+The name of a module is duplicated in the XML but anyway, try to keep ``name``
+attribute and ``module`` element in sync.
+
+To create a new item which triggers some wxGUI action defined in distribution
+use ``<wxgui-item>`` tag:
+
+.. code-block:: xml
+
+    <wxgui-item name="RasterMapCalculator"/>
+
+Note that now it is not possible to create custom wxGUI items.
+
+To include an existing toolbox use ``<subtoolbox>`` tag:
+
+.. code-block:: xml
+
+    <subtoolbox name="NeighborhoodAnalysis"/>
+
+To create a submenu in your new menu (toolbox), you need to create a new toolbox
+and include this toolbox.
+
+To create your custom main menu create a file main_menu.xml in your user home
+directory, in ``.grass7/toolboxes`` subdirectory. Directory ``.grass7`` may be
+hidden directory on your system. The XML file should contain the definition of
+only one toolbox. The name attribute and label element are not used but should
+be filled for documentation purposes and future compatibility.
+
+If you want to base your toolbox or main menu on existing toolbox or main menu
+copy the part of existing XML file from GRASS GIS distribution (installation)
+directory or GRASS GIS source code. If you want to include some existing
+toolboxes or wxGUI items defined in GRASS GIS you need to look to these files
+too and find the proper ``name`` attributes.
+
+
+Example
+^^^^^^^
+
+Files should be placed in user home directory in ``.grass7/toolboxes``
+subdirectory, e.g. ``/home/john/.grass7/toolboxes``.
+
+toolboxes.xml
+"""""""""""""
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE toolboxes SYSTEM "toolboxes.dtd">
+    <toolboxes>
+      <toolbox name="MyRaster">
+        <label>My &amp;raster</label>
+        <items>
+          <module-item name="r.buffer">
+            <label>Buffer rasters</label>
+          </module-item>
+          <module-item name="r.mask">
+            <label>Mask</label>
+          </module-item>
+          <separator/>
+          <wxgui-item name="RasterMapCalculator"/>
+          <subtoolbox name="NeighborhoodAnalysis"/>
+          <subtoolbox name="ReportAndStatistics"/>
+        </items>
+      </toolbox>
+    </toolboxes>
+
+
+main_menu.xml
+"""""""""""""
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE toolbox SYSTEM "main_menu.dtd">
+    <toolbox name="MyCustomMainMenu">
+      <label>MyCustomMainMenu</label>
+      <items>
+        <subtoolbox name="File"/>
+        <subtoolbox name="Settings"/>
+        <subtoolbox name="MyRaster"/>
+        <subtoolbox name="Imagery"/>
+        <subtoolbox name="Help"/>
+      </items>
+    </toolbox>
+
+
+Validation
+^^^^^^^^^^
+
+You should validate your XML before running wxGUI, e.g. using ``xmllint``
+(no output means that document is valid)::
+
+    xmllint --noout --dtdvalid toolboxes.dtd toolboxes.xml
+
+You can find ``toolboxes.dtd`` and ``main_menu.dtd`` in your GRASS GIS directory,
+in ``etc/gui/wxpython/xml`` subdirectory. Depending on the validator,
+you might need to add DTD file to the drectory with the XML file.
+
+If you will provide an invalid, not well formed or empty file loading of
+toolboxes will obviously fail.
+
+
+Labels
+^^^^^^
+
+The label shortly describes the toolbox or the action which will happen after
+running an item. The label can be a command such as *"Create table"*
+or the general name such as *"Table management"*.
+You should add label to each toolbox you create and to each item you create.
+However, if you are just using (and thus referencing) existing items
+(or toolboxes), you don't need to include labels (so you can use just empty
+tags only with the name attribute).
+
+Important items in menu usually have a automatically assigned shortcut which
+depends on their label. This shortcut is assigned to ``Alt+Letter``
+(on most platforms) where letter is a letter after an ampersand (``&``) in the
+item label and  in the user interface the letter is underlined.
+Note that in XML you cannot write ``&`` but you have to write ``&amp;``.
+This concept is not related to the standard shortcut assigned to the item
+according to the shortcut in the XML file.
+
+Don't be confused with the label which is set for the module in the source code.
+These labels play different role, they must be short and usually
+with the wording of a command.

gui/wxpython/docs/wxgui_toolboxes/Makefile

@@ -1,107 +0,0 @@
-# Makefile for Sphinx documentation
-#
-MODULE_TOPDIR=../../../..
-include $(MODULE_TOPDIR)/include/Make/Vars.make
-include $(MODULE_TOPDIR)/include/Make/Rules.make
-
-
-PAPER         =
-BUILDDIR      = _build
-BUILDDIR_HTML = $(HTMLDIR)/wxgui_toolboxes
-
-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) .
-SPHINXBUILD     = sphinx-build
-SPHINXAPIDOC    = sphinx-apidoc
-
-# some distros come with a different name
-BUILD  := $(type $(SPHINXBUILD) >/dev/null)  || (SPHINXBUILD  = sphinx-build2)
-APIDOC := $(type $(SPHINXAPIDOC) >/dev/null) || (SPHINXAPIDOC = sphinx-apidoc2)
-
-checksphinx:
-	@echo "SPHINXBUILD: Found <$(SPHINXBUILD)>"
-	@echo "SPHINXAPIDOC: Found <$(SPHINXAPIDOC)>"
-	@(type $(SPHINXBUILD) > /dev/null || (echo "ERROR: Install 'sphinx-build' software first (get from http://sphinx-doc.org)" && exit 1))
-	@(type $(SPHINXAPIDOC) > /dev/null || (echo "ERROR: Install 'sphinx-apidoc' software first (get from http://sphinx-doc.org)" && exit 1))
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp checksphinx libpythonapidoc libpythonclean libpythondirhtml libpythondoctest libpythonepub libpythonhelp libpythonhtml libpythonlatex libpythonlatexpdf libpythonman libpythonsinglehtml
-
-.DEFAULT_GOAL := toolboxeshelp
-
-toolboxeshelp:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  toolboxeshtml       to make standalone HTML files"
-	@echo "  toolboxesdirhtml    to make HTML files named index.html in directories"
-	@echo "  toolboxessinglehtml to make a single large HTML file"
-	@echo "  toolboxesepub       to make an epub"
-	@echo "  toolboxeslatex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  toolboxeslatexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  toolboxesman        to make manual pages"
-	@echo "  toolboxesdoctest    to run all doctests embedded in the documentation (if enabled)"
-
-toolboxesclean:
-	-rm -rf $(BUILDDIR)
-	-rm -f _templates/layout.html
-
-toolboxesapidoc:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(call run_grass,$(SPHINXAPIDOC) -T -f -o src/ ../../core/)
-	
-toolboxeshtml:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(call run_grass,$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
-
-toolboxesdirhtml:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(call run_grass,$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR_HTML)"
-
-toolboxessinglehtml:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(call run_grass,$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR_HTML))
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR_HTML)"
-
-toolboxesepub:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(call run_grass,$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub)
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/"
-
-toolboxeslatex:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(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)."
-
-toolboxeslatexpdf:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(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/"
-
-toolboxesman:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(call run_grass,$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(MANDIR))
-	@echo
-	@echo "Build finished. The manual pages are in $(MANDIR)/"
-
-toolboxesdoctest:
-	@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
-	$(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."
-
-clean: toolboxesclean

gui/wxpython/docs/wxgui_toolboxes/_static/pygrass.css

@@ -1,74 +0,0 @@
-/* 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;
-}

gui/wxpython/docs/wxgui_toolboxes/_templates/layout.html.template

@@ -1,9 +0,0 @@
-{% 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 %}

gui/wxpython/docs/wxgui_toolboxes/conf.py

@@ -1,358 +0,0 @@
-# -*- 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')))
-
-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>&copy; 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',
-]
-todo_include_todos = True
-# 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'wxGUI toolboxes'
-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 = 'wxGUIdoc'
-
-
-# -- 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', 'wxGUI.tex', u'wxGUI 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', 'wxgui', u'wxGUI 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', 'wxGUI', u'wxGUI Documentation',
-   u'GRASS Development Team', 'wxGUI', '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'wxGUI'
-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

gui/wxpython/docs/wxgui_toolboxes/make.bat

@@ -1,242 +0,0 @@
-@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

gui/wxpython/docs/wxgui_toolboxes/src/.directory

@@ -1,4 +0,0 @@
-[Dolphin]
-Timestamp=2014,9,30,22,30,38
-Version=3
-ViewMode=1

gui/wxpython/docs/wxgui_toolboxes/src/files_overview.rst

@@ -1,98 +0,0 @@
-Files overview
-==============
-
-Files related to toolboxes
---------------------------
-
-GRASS source code contains these XML files:
-
-*   ``gui/wxpython/xml/main_menu.xml``
-
-
-
-
-*   ``gui/wxpython/xml/toolboxes.xml``
-
-
-
-
-*   ``gui/wxpython/xml/wxgui_items.xml``
-
-
-
-
-GRASS distribution contains these XML files:
-
-*   ``etc/gui/wxpython/xml/main_menu.xml``
-
-
-
-
-*   ``etc/gui/wxpython/xml/toolboxes.xml``
-
-
-
-
-*   ``etc/gui/wxpython/xml/wxgui_items.xml``
-
-
-
-
-*   ``etc/gui/wxpython/xml/module_items.xml``
-    (generated during compilation)
-
-
-
-*   ``etc/gui/wxpython/xml/menudata.xml``
-    (generated during compilation)
-
-
-
-GRASS directory (
-``".grass7"``
-) in user home directory (i.e.,
-``"$HOME"``
-on Unix) contains these XML files:
-
-*   ``toolboxes/main_menu.xml``
-    (created by user)
-
-
-
-*   ``toolboxes/toolboxes.xml``
-    (created by user)
-
-
-
-*   ``toolboxes/menudata.xml``
-    (generated on wxGUI startup)
-
-
-
-
-Other files
------------
-
-GRASS source code contains these XML files:
-
-*   ``gui/wxpython/xml/menudata_gmodeler.xml``
-
-
-
-
-*   ``gui/wxpython/xml/menudata_psmap.xml``
-
-
-
-
-In GRASS distribution these XML files are in the
-``etc/gui/wxpython/xml``
-directory.
-
-|toolboxes_flowchart.png|
-
-
-.. |toolboxes_flowchart.png| image:: toolboxes_flowchart.png
-    :width: 6.9252in
-    :height: 6.2957in
-

gui/wxpython/docs/wxgui_toolboxes/src/generation_of_files_and_menu.rst

@@ -1,50 +0,0 @@
-Generation of files and menu
-============================
-
-As noted in the section
-`Files overview <index.htmlsOverview>`_
-, there are files in the GRASS distribution and in the user home directory (particularly in
-``".grass7/toolboxes"``
-subdirectory).
-
-When user doesn't have any
-``toolboxes.xml``
-or
-``main_menu.xml``
-files in the home directory, file
-``menudata.xml``
-included in the distribution is used to build a menu.
-
-When
-``toolboxes.xml``
-or
-``main_menu.xml``
-file (in user home directory) is newer than
-``menudata.xml``
-in user home directory or
-``menudata.xml``
-does not exists in user home directory, the
-``menudata.xml``
-is generated when GUI starts.
-
-When
-``menudata.xml``
-in user home directory is fresh enough, it is used to create a menu.
-
-When
-``toolboxes.xml``
-or
-``main_menu.xml``
-file is not in user home directory but
-``menudata.xml``
-is, the file is re-generated (each time the GUI starts). So, if you just have your own
-``main_menu.xml``
-, it is better to create also a
-``toolboxes.xml``
-file with no toolboxes (note that you still need to create a valid XML toolbox file). Similarly, if you have only the
-``toolboxes.xml``
-file, it is better to copy the
-``main_menu.xml``
-file from distribution into your home directory.
-
-When reading the main_menu file, user toolboxes are expanded first and then toolboxes from distribution are expanded.

gui/wxpython/docs/wxgui_toolboxes/src/how_to_write_a_custom_toolbox.rst

@@ -1,184 +0,0 @@
-How to write a custom toolbox
-=============================
-
-To create a new toolbox use
-``"<toolbox>"``
-tag:
-
-<toolbox name="MyRaster">
-
-<label>My &amp;raster</label>
-
-<items>
-
-...
-
-</items>
-
-</toolbox>
-
-To create a new item which represents a module use
-``"<module-item>"``
-tag:
-
-<module-item name="r.buffer">
-
-<label>Buffer rasters</label>
-
-</module-item>
-
-This works for modules contained in distribution. For modules from addons or some your modules
-which are on path use
-``"<module-item>"``
-tag together with
-``"<module>"``
-tag:
-
-<module-item name="r.agent">
-
-<label>Buffer rasters</label>
-
-<module>r.agent</module>
-
-</module-item>
-
-The name of a module is duplicated in the XML but anyway, try to keep
-``name``
-attribute and
-``module``
-element in sync.
-
-To create a new item which triggers some wxGUI action defined in distribution use
-``"<wxgui-item>"``
-tag:
-
-<wxgui-item name="RasterMapCalculator"/>
-
-Note that now it is not possible to create custom wxGUI items.
-
-To include an existing toolbox use
-``"<subtoolbox>"``
-tag:
-
-<subtoolbox name="NeighborhoodAnalysis"/>
-
-To create a submenu in your new menu (toolbox), you need to create a new toolbox and include this toolbox.
-
-To create your custom main menu create a file main_menu.xml in your user home directory, in .grass7/toolboxes subdirectory. Directory .grass7 may be hidden directory on your system. The XML file should contain the definition of only one toolbox. The name attribute and label element are not used but should be filled for documentation purposes and future compatibility.
-
-If you want to base your toolbox or main menu on existing toolbox or main menu copy the part of existing XML file from GRASS GIS distribution (installation) directory or GRASS GIS source code. If you want to include some existing toolboxes or wxGUI items defined in GRASS GIS you need to look to these files too and find the proper
-``name``
-attributes.
-
-Example
--------
-
-Files should be placed in user home directory in .grass7/toolboxes subdirectory, e.g.
-``/home/john/``
-.grass7/toolboxes.
-
-toolboxes.xml
-
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!DOCTYPE toolboxes SYSTEM "toolboxes.dtd">
-
-<toolboxes>
-
-<toolbox name="MyRaster">
-
-<label>My &amp;raster</label>
-
-<items>
-
-<module-item name="r.buffer">
-
-<label>Buffer rasters</label>
-
-</module-item>
-
-<module-item name="r.mask">
-
-<label>Mask</label>
-
-</module-item>
-
-<separator/>
-
-<wxgui-item name="RasterMapCalculator"/>
-
-<subtoolbox name="NeighborhoodAnalysis"/>
-
-<subtoolbox name="ReportAndStatistics"/>
-
-</items>
-
-</toolbox>
-
-</toolboxes>
-
-main_menu.xml
-
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!DOCTYPE toolbox SYSTEM "main_menu.dtd">
-
-<toolbox name="MyCustomMainMenu">
-
-<label>MyCustomMainMenu</label>
-
-<items>
-
-<subtoolbox name="File"/>
-
-<subtoolbox name="Settings"/>
-
-<subtoolbox name="MyRaster"/>
-
-<subtoolbox name="Imagery"/>
-
-<subtoolbox name="Help"/>
-
-</items>
-
-</toolbox>
-
-Validation
-----------
-
-You should validate your XML before running wxGUI, e.g. using
-``xmllint``
-(no output means that document is valid):
-
-xmllint --noout --dtdvalid toolboxes.dtd toolboxes.xml
-
-You can find
-``toolboxes.dtd``
-and
-``main_menu.dtd``
-in your GRASS GIS directory, in
-``etc/gui/wxpython/xml``
-subdirectory.
-
-If you will provide an invalid, not well formed or empty file loading of toolboxes will obviously fail.
-
-Labels
-------
-
-The label shortly describes the toolbox or the action which will happen after running an item. The label can be a command such as
-*"Create table"*
-or the general name such as
-*"Table management"*
-. You should add label to each toolbox you create and to each item you create. However, if you are just using (and thus referencing) existing items (or toolboxes), you don't need to include labels (so you can use just empty tags only with the name attribute).
-
-Important items in menu usually have a automatically assigned shortcut which depends on their label. This shortcut is assigned to
-``Alt+Letter``
-(On most platforms) where letter is a letter after an ampersand (
-``&``
-) in the item label and in the user interface the letter is underlined. Note that in XML you cannot write
-``"&"``
-but you have to write
-``"&amp;"``
-. This concept is not related to the standard shortcut assigned to the item according to the shortcut in the XML file.
-
-Don't be confused with the label which is set for the module in the source code.

gui/wxpython/docs/wxgui_toolboxes/src/index.rst

@@ -1,68 +0,0 @@
-WxGUI Toolboxes
-
-Table of Contents
-~~~~~~~~~~~~~~~~~
-
-*   `Introduction <introduction.html>`_
-
-
-*   `Files overview <index.html>`_
-
-    *   `Files related to toolboxes <index.html>`_
-
-
-    *   `Other files <toolboxes_file.html>`_
-
-
-
-*   `Generation of files and menu <generation_of_files_and_menu.html>`_
-
-
-
-*   `Toolboxes file <toolboxes_file.html>`_
-
-
-
-*   `Main menu file <main_menu_file.html>`_
-
-
-
-*   `Modules items file <module_items_file.html>`_
-
-
-
-*   `wxGUI items file <wxgui_items_file.html>`_
-
-
-
-*   `Menudata file <menudata_file.html>`_
-
-
-
-*   `How to write a custom toolbox <how_to_write_a_custom_toolbox.html>`_
-
-    *   `Example <how_to_write_a_custom_toolbox.html>`_
-
-
-
-    *   `Validation <how_to_write_a_custom_toolbox.html>`_
-
-
-
-    *   `Labels <how_to_write_a_custom_toolbox.html>`_
-
-
-
-
-.. toctree::
-    :maxdepth: 2
-
-    Introduction
-    Files_overview
-    Generation_of_files_and_menu
-    Toolboxes_file
-    Main_menu_file
-    Modules_items_file
-    wxGUI_items_file
-    Menudata_file
-    How_to_write_a_custom_toolbox

gui/wxpython/docs/wxgui_toolboxes/src/introduction.rst

@@ -1,16 +0,0 @@
-Introduction
-============
-
-wxGUI toolboxes enables GUI customization and organization of menu (and other views) according to user needs.
-
-XML files are used for code generation and in case of toolboxes enables wxGUI (menu) customization.
-
-Currently, all the files described here are related to the menus which are generated from these files. The most of the files described here are the part of implementation of toolboxes in wxGUI.
-
-Each XML file has a DTD file which can by used for validation. XSD files are not provided (but this can change in the future). Some file types can occur multiple times, some occur only once.
-
-Note that in XML context, the term
-*tag*
-partially overlaps with the term
-*element*
-. Element emphasizes the XML structure, XML object model and content of these objects. Tag emphasizes the markup and the name of the element.

gui/wxpython/docs/wxgui_toolboxes/src/main_menu_file.rst

@@ -1,12 +0,0 @@
-Main menu file
-==============
-
-File has a layout similar to the
-`Toolboxes file <toolboxes_file.html>`_
-but contains only one
-``toolbox``
-which can contain only
-``subtoolbox``
-es and one special item
-``user-toolboxes-list``
-which will be replaced by a menu with the list of toolboxes in the user toolbox file.

gui/wxpython/docs/wxgui_toolboxes/src/menudata_file.rst

@@ -1,8 +0,0 @@
-Menudata file
-=============
-
-Historically, menudata.xml file was in the source codes and was partially maintained by the script
-``gui/wxpython/tools/update_menudata.py``
-which updated the description and keywords (based on module's module->label or module->description, module->keywords). Other items (menu structure, menu item labels and non-module only items) were edited in the menudata.xml file directly.
-
-Currently, the file is generated during compilation or at startup. It serves as an intermediate layer between all toolboxes XMLs and GUI menu tree generation.

gui/wxpython/docs/wxgui_toolboxes/src/modules_items_file.rst

@@ -1,28 +0,0 @@
-Modules items file
-==================
-
-The file contains information obtained from modules' interface descriptions. The structure of one
-``"module-item"``
-is the same as in the
-`Toolboxes file <toolboxes_file.html>`_
-but some subelements are mandatory.
-
-File contained in distribution is generated during compilation from available modules using the script
-``gui/wxpython/tools/build_modules_xml.py``
-.
-
-Element
-``"<module>"``
-is the name of the executable, e.g. "r.info".
-
-Element
-``"<label>"``
-is currently not present. It represents the short label in menu and it is added in toolboxes.
-
-Element
-``"<description>"``
-is created from module's module->description (or if it exists, module->label concatenated with module->description).
-
-Element
-``"<keywords>"``
-is created from module's module->keywords.

gui/wxpython/docs/wxgui_toolboxes/src/toolboxes_file.rst

@@ -1,28 +0,0 @@
-Toolboxes file
-==============
-
-This file contains definition of toolboxes. A toolbox contains references (links) to other items, namely
-``"<module-items>"``
-,
-``"<wxgui-items>"``
-and other toolboxes using tag
-``"<subtoolbox>"``
-. Tag
-``"<separator>"``
-is used when the view supports some kind of visual separators to group parts of the toolbox (or menu).
-
-Items are referenced using
-``name``
-attribute. In case of
-``"<module-items>"``
-,
-``"<wxgui-items>"``
-also subelements can be added to create new items or to replace subelements values from item definition.
-
-|toolboxes_filestructure.png|
-
-
-.. |toolboxes_filestructure.png| image:: toolboxes_filestructure.png
-    :width: 6.9252in
-    :height: 6.2957in
-

gui/wxpython/docs/wxgui_toolboxes/src/wxgui_items_file.rst

@@ -1,8 +0,0 @@
-wxGUI items file
-================
-
-The file contains definitions of wxGUI actions which can be accessed for example, from menu. The structure of one
-``"wxgui-item"``
-is the same as in
-`Toolboxes file <toolboxes_file.html>`_
-but some subelements are mandatory.