Refactor operation doc pages

Extended the use of the :option: directive to all currently written
operation doc pages. In the process several more default parameters were
added for easy inclusion in other doc pages.

Expanded the info tables for each operation with "domain", "alias",
"input type" and "output type".

Corrected various errors along the way. Mainly formatting errors and
references to invalid parameters such as +sym in hatano.

5 files changed, 233 insertions, 86 deletions

diff --git a/docs/source/operations/transformations/deformation.rst b/docs/source/operations/transformations/deformation.rst
index f10562dd..f3cb9307 100644
--- a/docs/source/operations/transformations/deformation.rst
+++ b/docs/source/operations/transformations/deformation.rst
@@ -4,6 +4,8 @@
 Kinematic datum shifting utilizing a deformation model
 ================================================================================
 
+.. versionadded:: 5.0.0
+
 Perform datum shifts means of a deformation/velocity model.
 
 +-----------------+--------------------------------------------------------------------+
@@ -11,19 +13,14 @@ Perform datum shifts means of a deformation/velocity model.
 +-----------------+--------------------------------------------------------------------+
 | **Output type** | Cartesian coordinates (spatial), decimalyears (temporal).          |
 +-----------------+--------------------------------------------------------------------+
-| **Options**                                                                          |
-+-----------------+--------------------------------------------------------------------+
-| `xy_grids`      | Comma-separated list of grids to load. *Required*.                 |
-+-----------------+--------------------------------------------------------------------+
-| `z_grids`       | Comma-separated list of grids to load. *Required*.                 |
++ **Domain**      | 4D                                                                 |
 +-----------------+--------------------------------------------------------------------+
-| `t_epoch`       | Central epoch of transformation. [decimalyear]. *Required*.        |
+| **Input type**  | Geodetic coordinates                                               |
 +-----------------+--------------------------------------------------------------------+
-| `t_obs`         | Observation time of coordinate(s). [decimalyear]. *Optional*.      |
-|                 | If not specified, will be get from the t component of 4D input     |
-|                 | points.                                                            |
+| **Output type** | Geodetic coordinates                                               |
 +-----------------+--------------------------------------------------------------------+
 
+
 The deformation operation is used to adjust coordinates for intraplate deformations.
 Usually the transformation parameters for regional plate-fixed reference frames such as
 the ETRS89 does not take intraplate deformation into account. It is assumed that
@@ -49,6 +46,7 @@ official ETRS89 transformations so in order to get accurate transformations in t
 countries it is necessary to apply the deformation model. The transformation from ITRF2008
 to the Danish realisation of ETRS89 is in PROJ described as::
 
+
     proj =  pipeline ellps = GRS80
             # ITRF2008@t_obs -> ITRF2000@t_obs
     step    init = ITRF2008:ITRF2000
@@ -81,8 +79,46 @@ model. The first use of the deformation operation is::
 
 Here we set the central epoch of the transformation, 2000.0. The observation epoch
 is expected as part of the input coordinate tuple. The deformation model is
-described by two grids, specified with *xy_grids* and *z_grids*. The first is
-the horizontal part of the model and the second is the vertical component.
+described by two grids, specified with :option:`+xy_grids` and :option:`+z_grids`.
+The first is the horizontal part of the model and the second is the vertical
+component.
+
+Parameters
+-------------------------------------------------------------------------------
+
+Required
+################################################################################
+
+
+.. option:: +xy_grids=<list>
+
+    Comma-separated list of grids to load. If a grid is prefixed by an `@` the
+    grid is consideres optional and PROJ will the not complain if the grid is
+    not available.
+
+    Grids for the horizontla component of a deformation model is expected to be
+    in CTable2 format.
+
+.. option:: +z_grids=<list>
+
+    Comma-separated list of grids to load. If a grid is prefixed by an `@` the
+    grid is consideres optional and PROJ will the not complain if the grid is
+    not available.
+
+    Grids for the vertical component of a deformation model is expected to be
+    in either GTX format.
+
+.. option:: +t_epoch=<value>
+
+    Central epoch of transformation given in decimalyears.
+
+Optional
+################################################################################
+
+.. option:: +t_obs=<value>
+
+    Observation time of coordinate(s) given in decimalyears. If not specified,
+    the observation time from the temporal component of 4D input points is used.
 
 Mathematical description
 -------------------------------------------------------------------------------
@@ -122,7 +158,7 @@ Coordinates of the gridded model are in ENU (east, north, up) space because it w
 otherwise require an enormous 3 dimensional grid to handle the corrections in cartesian
 space. Keeping the correction in lat/long space reduces the complexity of the grid
 significantly. Consequently though, the input coordinates needs to be converted to
-lat/long space when searching for corrections in the grid. This is done with *cart*
+lat/long space when searching for corrections in the grid. This is done with the *cart*
 operation. The converted grid corrections can then be applied to the input coordinates
 in cartesian space. The conversion from ENU space to cartesian space is done in the
 following way:
diff --git a/docs/source/operations/transformations/helmert.rst b/docs/source/operations/transformations/helmert.rst
index 941fc676..a3e43c13 100644
--- a/docs/source/operations/transformations/helmert.rst
+++ b/docs/source/operations/transformations/helmert.rst
@@ -4,59 +4,26 @@
 Helmert transform
 ================================================================================
 
+.. versionadded:: 5.0.0
+
 The Helmert transformation changes coordinates from one reference frame to
 anoether by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and
 14-parameter kinematic counterparts.
 
+
++-----------------+-------------------------------------------------------------------+
+| **Alias**       | helmert                                                           |
++-----------------+-------------------------------------------------------------------+
++ **Domain**      | 2D, 3D and 4D                                                     |
 +-----------------+-------------------------------------------------------------------+
 | **Input type**  | Cartesian coordinates (spatial), decimalyears (temporal).         |
 +-----------------+-------------------------------------------------------------------+
 | **Output type** | Cartesian coordinates (spatial), decimalyears (temporal).         |
 +-----------------+-------------------------------------------------------------------+
-| **Options**                                                                         |
-+----------------+--------------------------------------------------------------------+
-| `x`            | Translation of the x-axis [m]. *Optional*.                         |
-+----------------+--------------------------------------------------------------------+
-| `y`            | Translation of the y-axis [m]. *Optional*.                         |
-+----------------+--------------------------------------------------------------------+
-| `z`            | Translation of the z-axis. [m]. *Optional*.                        |
-+----------------+--------------------------------------------------------------------+
-| `s`            | Scale factor [ppm]. *Optional*.                                    |
-+----------------+--------------------------------------------------------------------+
-| `rx`           | X-axis rotation in the 3D Helmert [arc seconds]. *Optional*.       |
-+----------------+--------------------------------------------------------------------+
-| `ry`           | Y-axis rotation in the 3D Helmert [arc seconds]. *Optional*.       |
-+----------------+--------------------------------------------------------------------+
-| `rz`           | Z-axis rotation in the 3D Helmert [arc seconds]. *Optional*.       |
-+----------------+--------------------------------------------------------------------+
-| `theta`        | Rotation angle in the 2D Helmert. [arc seconds]. *Optional*.       |
-+----------------+--------------------------------------------------------------------+
-| `dx`           | Translation rate of the x-axis. [m/year]. *Optional*.              |
-+----------------+--------------------------------------------------------------------+
-| `dy`           | Translation rate of the y-axis. [m/year]. *Optional*.              |
-+----------------+--------------------------------------------------------------------+
-| `dz`           | Translation rate of the z-axis. [m/year]. *Optional*.              |
-+----------------+--------------------------------------------------------------------+
-| `ds`           | Scale rate factor [ppm/year]. *Optional*.                          |
-+----------------+--------------------------------------------------------------------+
-| `drx`          | Rotation rate of the x-axis [arc seconds/year]. *Optional*.        |
-+----------------+--------------------------------------------------------------------+
-| `dry`          | Rotation rate of the y-axis [arc seconds/year]. *Optional*.        |
-+----------------+--------------------------------------------------------------------+
-| `drz`          | Rotation rate of the y-axis [arc seconds/year]. *Optional*.        |
-+----------------+--------------------------------------------------------------------+
-| `t_epoch`      | Central epoch of transformation. [decimalyear]. Only used in       |
-|                | spatiotemporal transformations. *Optional*.                        |
-+----------------+--------------------------------------------------------------------+
-| `t_obs`        | Observation time of coordinate(s). Mostly useful in 2D and 3D      |
-|                | transformations. [decimalyear]. *Optional*.                        |
-|                | If not specified, will be get from the t component of 4D input     |
-|                | points.                                                            |
-+----------------+--------------------------------------------------------------------+
-| `exact`        | Use exact transformation equations. *Optional*.                    |
-+----------------+--------------------------------------------------------------------+
-| `transpose`    | Transpose rotation matrix. *Optional*.                             |
-+----------------+--------------------------------------------------------------------+
+| **Input type**  | Cartesian coordinates                                             |
++-----------------+-------------------------------------------------------------------+
+| **Output type** | Cartesian coordinates                                             |
++-----------------+-------------------------------------------------------------------+
 
 The Helmert transform, in all it's various incarnations, is used to perform reference
 frame shifts. The transformation operates in cartesian space. It can be used to transform
@@ -107,6 +74,102 @@ Transformation from `ITRF2000@2017.0`  to `ITRF93@2017.0` using 15 parameters:
          drx=-0.00011 dry=-0.00019 drz=0.00007
          epoch=1988.0 tobs=2017.0    transpose
 
+Parameters
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. note::
+
+    All parameters are optional but at least one should be used, otherwise the
+    operation will return the coordinates unchanged.
+
+.. option:: +x=<value>
+
+    Translation of the x-axis given in meters.
+
+.. option:: +y=<value>
+
+    Translation of the x-axis given in meters.
+
+.. option:: +z=<value>
+
+    Translation of the z-axis given in meters.
+
+.. option:: +s=<value>
+
+    Scale factor given in ppm.
+
+.. option:: +rx=<value>
+
+    X-axis rotation in the 3D Helmert given arc seconds.
+
+
+.. option:: +ry=<value>
+
+    Y-axis rotation in the 3D Helmert given in arc seconds.
+
+.. option:: +rz=<value>
+
+    Z-axis rotation in the 3D Helmert given in arc seconds.
+
+
+.. option:: +theta=<value>
+
+    Rotation angle in the 2D Helmert given in arc seconds.
+
+.. option:: +dx=<value>
+
+    Translation rate of the x-axis given in m/year.
+
+.. option:: +dy=<value>
+
+    Translation rate of the y-axis given in m/year.
+
+.. option:: +dz=<value>
+
+    Translation rate of the z-axis given in m/year.
+
+.. option:: +ds=<value>
+
+    Scale rate factor given in ppm/year.
+
+.. option:: +drx=<value>
+
+    Rotation rate of the x-axis given in arc seconds/year.
+
+.. option:: +dry=<value>
+
+    Rotation rate of the y-axis given in arc seconds/year.
+
+.. option:: +drz=<value>
+
+    Rotation rate of the y-axis given in arc seconds/year.
+
+.. option:: +t_epoch=<value>
+
+    Central epoch of transformation given in decimalyear. Only used
+    spatiotemporal transformations.
+
+.. option:: +t_obs=<value>
+
+    Observation time of coordinate(s) given in decicalyear. Mostly useful
+    in 2D and 3D transformations where the observation time is not passed
+    as part of the input coordinate. Can be used to override the observation
+    time from the input coordinate.
+
+.. option:: +exact
+
+    Use exact transformation equations.
+
+    See :eq:`rot_exact`
+
+.. option:: +transpose
+
+    Transpose rotation matrix and follow the **Cordinate Frame** rotation
+    convention. If :option:`+transpose` is not added the **Position Vector**
+    rotation convention is used.
+
+
+
 Mathematical description
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -244,6 +307,7 @@ The three rotation matrices can be combined in one:
         \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y}
     \end{align}
 
+
 For :math:`\mathbf{R}`, this yields:
 
 .. math::
@@ -302,9 +366,10 @@ using the approximated rotation matrix:
 
 If the rotation matrix is transposed the transformation is effectively reversed.
 This is cause for some confusion since there is no correct way of defining the
-rotation matrix. Two conventions exists and they seem to be equally popular.
-In PROJ the rotation matrix can be transposed by adding the `transpose` flag in
-the transformation setup.
+rotation matrix. Two conventions exists and they seem to be equally popular. PROJ
+uses the **Position Vector** rotation convention. The rotation matrix can be transposed by
+adding the :option:`+transpose` flag in the transformation setup which makes PROJ
+follow the **Coordinate Frame** rotation convention.
 
 Applying :eq:`propagation` we get the kinematic version of the approximated
 3D Helmert:
diff --git a/docs/source/operations/transformations/hgridshift.rst b/docs/source/operations/transformations/hgridshift.rst
index 63fa5122..35c84919 100644
--- a/docs/source/operations/transformations/hgridshift.rst
+++ b/docs/source/operations/transformations/hgridshift.rst
@@ -4,17 +4,18 @@
 Horizontal grid shift
 ================================================================================
 
+.. versionadded:: 5.0.0
+
 Change of horizontal datum by grid shift.
 
+
++-----------------+--------------------------------------------------------------------+
+| **Domain**      | 2D                                                                 |
 +-----------------+--------------------------------------------------------------------+
 | **Input type**  | Geodetic coordinates.                                              |
 +-----------------+--------------------------------------------------------------------+
 | **Output type** | Geodetic coordinates.                                              |
 +-----------------+--------------------------------------------------------------------+
-| **Options**                                                                          |
-+-----------------+--------------------------------------------------------------------+
-| `+grids`        | Comma-separated list of grids to load.                             |
-+-----------------+--------------------------------------------------------------------+
 
 The horizontal grid shift is done by offsetting the planar input coordinates by
 a specific amount determined by the loaded grids. The simplest use case of the
@@ -37,3 +38,15 @@ list.
 PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details
 about all three formats can be found in the GDAL documentation. GDAL reads and
 writes all three formats. Using GDAL for construction of new grids is recommended.
+
+
+Parameters
+################################################################################
+
+.. option:: +grids=<list>
+
+    Comma-separated list of grids to load. If a grid is prefixed by an `@` the
+    grid is consideres optional and PROJ will the not complain if the grid is
+    not available.
+
+    Grids are expected to be in CTable2, NTv1 or NTv2 format.
diff --git a/docs/source/operations/transformations/molodensky.rst b/docs/source/operations/transformations/molodensky.rst
index d4ff3e79..a90828cd 100644
--- a/docs/source/operations/transformations/molodensky.rst
+++ b/docs/source/operations/transformations/molodensky.rst
@@ -4,6 +4,8 @@
 Molodensky transform
 ================================================================================
 
+.. versionadded:: 5.0.0
+
 The Molodensky transformation resembles a :ref:`Helmert` with zero
 rotations and a scale of unity, but converts directly from geodetic coordinates to
 geodetic coordinates, without the intermediate shifts to and from cartesian
@@ -17,28 +19,13 @@ reasons, but nevertheless indispensable due to the large amount of data that has
 already been transformed that way [EversKnudsen2017]_.
 
 +---------------------+----------------------------------------------------------+
-| **Input type**      | Geodetic coordinates.                                    |
-+---------------------+----------------------------------------------------------+
-| **Output type**     | Geodetic coordinates.                                    |
-+---------------------+----------------------------------------------------------+
-| **Options**                                                                    |
-+---------------------+----------------------------------------------------------+
-| `+da`               | Difference in semimajor axis of the defining ellipsoids. |
-+---------------------+----------------------------------------------------------+
-| `+df`               | Difference in flattening of the defining ellipsoids.     |
-+---------------------+----------------------------------------------------------+
-| `+dx`               | Offset of the X-axes of the defining ellipsoids.         |
+| **Alias**           | molodensky                                               |
 +---------------------+----------------------------------------------------------+
-| `+dy`               | Offset of the Y-axes of the defining ellipsoids.         |
+| **Domain**          | 3D                                                       |
 +---------------------+----------------------------------------------------------+
-| `+dz`               | Offset of the Z-axes of the defining ellipsoids.         |
+| **Input type**      | Geodetic coordinates (horizontal), meters (vertical)     |
 +---------------------+----------------------------------------------------------+
-| `+ellps`            | Ellipsoid definition of source coordinates.              |
-|                     | Any specification can be used (e.g. `+a`, `+rf`, etc).   |
-|                     | If not specified, default ellipsoid is used.             |
-+---------------------+----------------------------------------------------------+
-| `+abridged`         | Use the abridged version of the Molodensky transform.    |
-|                     | Optional.                                                |
+| **output type**     | Geodetic coordinates (horizontal), meters (vertical)     |
 +---------------------+----------------------------------------------------------+
 
 The Molodensky transform can be used to perform a datum shift from coordinate
@@ -72,3 +59,38 @@ The same transformation using the standard Molodensky::
 
     proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8  dx=-134 dy=-48 dz=149
 
+
+Parameters
+################################################################################
+
+Required
+-------------------------------------------------------------------------------
+
+.. option:: +da=<value>
+
+    Difference in semimajor axis of the defining ellipsoids.
+
+.. option:: +df=<value>
+
+    Difference in flattening of the defining ellipsoids.
+
+.. option:: +dx=<value>
+
+    Offset of the X-axes of the defining ellipsoids.
+
+.. option:: +dy=<value>
+
+    Offset of the Y-axes of the defining ellipsoids.
+
+.. option:: +dz=<value>
+
+    Offset of the Z-axes of the defining ellipsoids.
+
+.. include:: ../options/ellps.rst
+
+Optional
+-------------------------------------------------------------------------------
+
+.. option:: +abridged
+
+    Use the abridged version of the Molodensky transform.
diff --git a/docs/source/operations/transformations/vgridshift.rst b/docs/source/operations/transformations/vgridshift.rst
index c583b273..ca2b421c 100644
--- a/docs/source/operations/transformations/vgridshift.rst
+++ b/docs/source/operations/transformations/vgridshift.rst
@@ -4,17 +4,17 @@
 Vertical grid shift
 ================================================================================
 
+.. versionadded:: 5.0.0
+
 Change Vertical datum change by grid shift
 
 +-----------------+--------------------------------------------------------------------+
+| **Domain**      | 3D                                                                 |
++-----------------+--------------------------------------------------------------------+
 | **Input type**  | Geodetic coordinates (horizontal), meters (vertical).              |
 +-----------------+--------------------------------------------------------------------+
 | **Output type** | Geodetic coordinates (horizontal), meters (vertical).              |
 +-----------------+--------------------------------------------------------------------+
-| **Options**                                                                          |
-+-----------------+--------------------------------------------------------------------+
-| `+grids`        | Comma-separated list of grids to load.                             |
-+-----------------+--------------------------------------------------------------------+
 
 The vertical grid shift is done by offsetting the vertical input coordinates by
 a specific amount determined by the loaded grids. The simplest use case of the
@@ -39,3 +39,14 @@ list.
 PROJ supports the GTX file format for vertical grid corrections. Details
 about all the format can be found in the GDAL documentation. GDAL both reads and
 writes the format. Using GDAL for construction of new grids is recommended.
+
+Parameters
+################################################################################
+
+.. option:: +grids=<list>
+
+    Comma-separated list of grids to load. If a grid is prefixed by an `@` the
+    grid is consideres optional and PROJ will the not complain if the grid is
+    not available.
+
+    Grids are expected to be in GTX format.