Docs restructuring in preparation for descriptions on tools usage.

docs/source/examples_2D.rst

@@ -165,7 +165,7 @@ You can now view an image of the B-scan using the command:
 
 .. code-block:: none
 
-    python -m tools.plot_Bscan cylinder_Bscan_2D_all.out Ez
+    python -m tools.plot_Bscan cylinder_Bscan_2D_all.out --field Ez
 
 :numref:`cylinder_Bscan_results` shows the B-scan (image of the Ez field). As expected a hyperbolic response is present from the metal cylinder.
 

docs/source/helper.rst

@@ -0,0 +1,7 @@
+.. _helper:
+
+****************
+Helper utilities
+****************
+
+This section provides information on how to use the Python modules (in the ``tools`` package) that help manage gprMax files.

docs/source/index.rst

@@ -19,6 +19,13 @@ gprMax User Guide
     geometry_snapshots
     output
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Tools
+
+    plotting
+    helper
+
 .. toctree::
     :maxdepth: 2
     :caption: Advanced topics
@@ -27,7 +34,7 @@ gprMax User Guide
 
 .. toctree::
     :maxdepth: 2
-    :caption: Help and Support
+    :caption: Support
 
     examples_2D
     examples_3D
@@ -38,5 +45,4 @@ gprMax User Guide
     :maxdepth: 2
     :caption: Appendices
 
-    app_waveforms
-    app_references
+    references

docs/source/output.rst

@@ -61,21 +61,6 @@ Within each individual ``tx`` group is the following dataset:
 Viewing output
 ==============
 
-There are a number of free tools available to read HDF5 files. Also MATLAB has high- and low-level functions for reading and writing HDF5 files, i.e. ``h5info`` and ``h5disp`` are useful for returning information and displaying the contents of HDF5 files respectively. gprMax includes some Python modules (in the ``tools`` package) to help you view output data:
-
-A-scans
--------
-
-* Plot A-scans using the Python module ``plot_Ascan.py``. The module uses matplotlib to plot the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window). Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Ascan my_outputfile.out``.
-
-* Plot A-scans using the MATLAB script ``plot_Ascan.m``. The script plots the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window).
-
-B-scans
--------
-
-gprMax produces a separate output file for each trace (A-scan) in the B-scan.
-
-* Combine the separate output files into one file using the Python module ``outputfiles_merge.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.outputfiles_merge basefilename modelruns``, where ``basefilename`` is the base name file of the output file series, e.g. for ``myoutput1.out``, ``myoutput2.out`` the base file name would be ``myoutput``, and ``modelruns`` is the number of output files to combine.
-* Plot an image of the B-scan using the Python module ``plot_Bscan.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Bscan my_outputfile.out field``, where ``field`` is the name of field to plot, e.g. ``Ex``, ``Ey`` or ``Ez``.
+There are a number of free tools available to read HDF5 files. Also MATLAB has high- and low-level functions for reading and writing HDF5 files, i.e. ``h5info`` and ``h5disp`` are useful for returning information and displaying the contents of HDF5 files respectively. gprMax includes some Python modules (in the ``tools`` package) to help you view output data. These are documented in the :ref:`tools section <plotting>`.
 
 

docs/source/plotting.rst

@@ -1,13 +1,35 @@
+
+.. _plotting:
+
+********
+Plotting
+********
+
+A-scans
+=======
+
+* Plot A-scans using the Python module ``plot_Ascan.py``. The module uses matplotlib to plot the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window). Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Ascan my_outputfile.out``.
+
+* Plot A-scans using the MATLAB script ``plot_Ascan.m``. The script plots the time history for the electric and magnetic field components for all receivers in a model (each receiver gets a separate figure window).
+
+B-scans
+=======
+
+gprMax produces a separate output file for each trace (A-scan) in the B-scan.
+
+* Combine the separate output files into one file using the Python module ``outputfiles_merge.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.outputfiles_merge basefilename modelruns``, where ``basefilename`` is the base name file of the output file series, e.g. for ``myoutput1.out``, ``myoutput2.out`` the base file name would be ``myoutput``, and ``modelruns`` is the number of output files to combine.
+* Plot an image of the B-scan using the Python module ``plot_Bscan.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Bscan my_outputfile.out field``, where ``field`` is the name of field to plot, e.g. ``Ex``, ``Ey`` or ``Ez``.
+
+
 .. _waveforms:
 
-******************
 Built-in waveforms
-******************
+==================
 
 This section provides definitions of the functions that are used to create the built-in waveforms. Example plots are shown using the parameters: amplitude of one, frequency of 1GHz, time window of 6ns, and a time step of 1.926ps.
 
 gaussian
-========
+--------
 
 A Gaussian waveform.
 
@@ -21,7 +43,7 @@ where :math:`I` is the current, :math:`\zeta = 2\pi^2f^2`, :math:`\chi=\frac{1}{
 
 
 gaussiandot
-===========
+-----------
 
 First derivative of a Gaussian waveform.
 
@@ -35,7 +57,7 @@ where :math:`I` is the current, :math:`\zeta = 2\pi^2f^2`, :math:`\chi=\frac{1}{
 
 
 gaussiandotnorm
-===============
+---------------
 
 Normalised first derivative of a Gaussian waveform.
 
@@ -49,7 +71,7 @@ where :math:`I` is the current, :math:`\zeta = 2\pi^2f^2`, :math:`\chi=\frac{1}{
 
 
 gaussiandotdot
-==============
+--------------
 
 Second derivative of a Gaussian waveform.
 
@@ -63,7 +85,7 @@ where :math:`I` is the current, :math:`\zeta = \pi^2f^2`, :math:`\chi=\frac{\sqr
 
 
 gaussiandotdotnorm
-==================
+------------------
 
 Normalised second derivative of a Gaussian waveform.
 
@@ -77,7 +99,7 @@ where :math:`I` is the current, :math:`\zeta = \pi^2f^2`, :math:`\chi=\frac{\sqr
 
 
 ricker
-======
+------
 
 A Ricker (or Mexican Hat) waveform which is the negative, normalised second derivative of a Gaussian waveform.
 
@@ -91,7 +113,7 @@ where :math:`I` is the current, :math:`\zeta = \pi^2f^2`, :math:`\chi=\frac{\sqr
 
 
 sine
-====
+----
 
 A single cycle of a sine waveform.
 
@@ -115,7 +137,7 @@ and
 
 
 contsine
-========
+--------
 
 A continuous sine waveform. In order to avoid introducing noise into the calculation the amplitude of the waveform is modulated for the first cycle of the sine wave (ramp excitation).