docs: restructuralize examples - move all of them into a dedicated dir

.flake8

@@ -20,7 +20,7 @@ per-file-ignores =
     # E741 ambiguous variable name 'l'
     man/build_html.py: E501
     man/build_md.py: E501
-    doc/python/m.distance.py: E501
+    doc/examples/python/m.distance.py: E501
     gui/scripts/d.wms.py: E501
     gui/wxpython/image2target/g.gui.image2target.py: E501
     gui/wxpython/photo2image/g.gui.photo2image.py: E501
@@ -45,6 +45,7 @@ per-file-ignores =
     python/grass/pydispatch/saferef.py: F821
     # C wrappers call libgis.G_gisinit before importing other modules.
     # TODO: Is this really needed?
+    python/grass/jupyter/__init__.py: E501
     python/grass/pygrass/vector/__init__.py: E402
     python/grass/pygrass/vector/__init__.py: E402
     python/grass/temporal/datetime_math.py: E722

.github/labeler.yml

@@ -145,7 +145,7 @@ notebook:
   - changed-files:
       - any-glob-to-any-file:
           - '**/*.ipynb'
-          - doc/notebooks/**
+          - doc/examples/notebooks/**
           - python/grass/jupyter/**
 C:
   - changed-files:

.github/workflows/python-code-quality.yml

@@ -190,8 +190,8 @@ jobs:
 
       - name: Test compiling example modules
         run: |
-          ( cd doc/raster/r.example/ && make )
-          ( cd doc/vector/v.example/ && make )
+          ( cd doc/examples/raster/r.example/ && make )
+          ( cd doc/examples/vector/v.example/ && make )
 
       - name: Run Sphinx to check API documentation build
         run: |

README.md

@@ -23,7 +23,7 @@ visualization.
 Launch this repository in Binder and experiment with GRASS's Python API in
 Jupyter Notebooks by clicking the button below:
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/OSGeo/grass/main?labpath=doc%2Fnotebooks%2Fjupyter_example.ipynb)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/OSGeo/grass/main?labpath=doc%2Fexamples%2Fnotebooks%2Fjupyter_example.ipynb)
 
 ## Contributing
 

doc/gui/wxpython/example/README → doc/examples/gui/wxpython/README

@@ -20,7 +20,7 @@ or it can be launched from the console.
 
 1. Go to GRASS root directory
 
-2. Copy directory ./doc/gui/wxpython/example to ./gui/wxpython/example
+2. Copy directory ./doc/examples/gui/wxpython to ./gui/wxpython
 
 3. Edit ./gui/wxpython/Makefile:
 

doc/gui/wxpython/example/frame.py → doc/examples/gui/wxpython/frame.py

@@ -41,8 +41,8 @@
 from example.dialogs import ExampleMapDialog
 
 # It is possible to call grass library functions (in C) directly via ctypes
-# however this is less stable. Example is available in trunk/doc/python/, ctypes
-# are used in nviz, vdigit, iclass gui modules.
+# however this is less stable. Example is available in trunk/doc/examples/python/,
+# ctypes are used in nviz, vdigit, iclass gui modules.
 
 # from ctypes import *
 # try:

doc/examples/gui/wxpython/g.gui.example.html

@@ -0,0 +1,66 @@
+<!-- meta page description: wxGUI Example Tool -->
+<!-- meta page index: wxGUI -->
+<h2>DESCRIPTION</h2>
+
+<p>
+The purpose of the <b>Example Tool</b> is to make life easier
+for new wxGUI developers. It can serve as a basic template when
+creating standalone GRASS GUI-based application. Example tool
+can display one raster map a show information about it.
+</p>
+
+<p>
+Following topics are covered:
+</p>
+
+<ul>
+  <li>creating standalone window</li>
+  <li>adding toolbars, statusbar</li>
+  <li>displaying raster map</li>
+  <li>running GRASS modules from application</li>
+  <li>creating dialog for element (raster, vector, ...) selection</li>
+  <li>using temporary region</li>
+  <li>access from main menu</li>
+  <li>writing programmer documentation</li>
+  <li>writing user documentation</li>
+</ul>
+
+<h2>NOTE</h2>
+
+See README to learn how to get Example Tool to work.
+
+<!--
+Put screenshot here
+<center>
+<br><img src="wxGUI_example.jpg" border="1"><br><br>
+</center>
+
+-->
+
+<h3>EXAMPLE TOOL TOOLBAR</h3>
+
+<dl>
+  <dt><img src="icons/layer-raster-add.png">&nbsp;
+    <em>Select raster layer</em></dt>
+  <dd>Select raster layer and compute statistics related to this layer.</dd>
+</dl>
+
+<h2>SEE ALSO</h2>
+
+<em>
+  <a href="wxGUI.html">wxGUI</a>,
+  <a href="wxGUI.components.html">wxGUI components</a>
+</em>
+
+<!--
+Create wiki page and put the link here:
+<p>
+See also
+user <a href="https://grasswiki.osgeo.org/wiki/WxGUI_...">wiki</a> page.
+</p>
+-->
+
+<h2>AUTHOR</h2>
+
+Anna Kratochvilova,
+<a href="https://www.cvut.cz">Czech Technical University in Prague</a>, Czech Republic

doc/notebooks/README.md → doc/examples/notebooks/README.md

@@ -5,8 +5,8 @@
 ### Using the notebooks locally
 
 Clone this repository with `git clone` first. Then, locally start the Jupyter
-notebook server from the command line in the `doc/notebooks/` directory
-containing the `*.ipynb` files with: `jupyter notebook`
+notebook server from the command line in the `doc/examples/notebooks/`
+directory containing the `*.ipynb` files with: `jupyter notebook`
 
 This will open a new browser tab or window with a list of the contents of the
 current working directory. Clicking on one of the `*.ipynb` files will start

doc/python/README → doc/examples/python/README

@@ -7,7 +7,7 @@ There are two ways of using Python to run GRASS commands:
 
 
 - Module creation using hooks into the C library functions using ctypes.
-  The scripts in the doc/python/examples/ directory will describe this.
+  The scripts in the doc/examples/python/ directory will describe this.
   (Ctypes is standard in Python 2.5 and newer; replaces the SWIG
   implementation in GRASS)
 

doc/raster/r.example/Makefile → doc/examples/raster/r.example/Makefile

@@ -1,6 +1,6 @@
 # fix this relative to include/
 # or use absolute path to the GRASS source code
-MODULE_TOPDIR = ../../..
+MODULE_TOPDIR = ../../../..
 
 PGM = r.example