From 859143489f765f9977515d206f03a4be25c0d67c Mon Sep 17 00:00:00 2001
From: snowman2 <alansnow21@gmail.com>
Date: Fri, 8 May 2020 20:34:44 -0500
Subject: [PATCH] DOC: Add transformation grid documentation page

---
 docs/api/datadir.rst          |  2 +
 docs/index.rst                |  1 +
 docs/installation.rst         | 18 ++-----
 docs/transformation_grids.rst | 92 +++++++++++++++++++++++++++++++++++
 4 files changed, 98 insertions(+), 15 deletions(-)
 create mode 100644 docs/transformation_grids.rst

diff --git a/docs/api/datadir.rst b/docs/api/datadir.rst
index 3b859a45b..938a8d609 100644
--- a/docs/api/datadir.rst
+++ b/docs/api/datadir.rst
@@ -1,3 +1,5 @@
+.. _data_directory:
+
 Data Directory
 ==============
 
diff --git a/docs/index.rst b/docs/index.rst
index 321b08d31..d7c676c5a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,7 @@ GitHub Repository: https://github.com/pyproj4/pyproj
 
    installation
    examples
+   transformation_grids
    gotchas
    advanced_examples
    build_crs
diff --git a/docs/installation.rst b/docs/installation.rst
index 98e96e37a..8ce9c8059 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -30,22 +30,10 @@ The easiest methods for installing pyproj are:
 If these installation methods do not meet your needs, the section below provides further instructions
 for getting setup.
 
+Transformation Grids
+=====================
 
-Datum Grids
-===========
-
-You can add datum grids to your PROJ data directory for better accuracy for some transformations.
-
-Available methods for download include:
-
-1. Download stable from https://download.osgeo.org/proj or latest from https://github.com/OSGeo/proj-datumgrid
-
-2. Use `conda <https://conda.io/en/latest/>`__ with the `conda-forge <https://conda-forge.org/>`__ channel:
-
-  .. code-block:: bash
-
-     conda install -c conda-forge proj-datumgrid-europe proj-datumgrid-north-america proj-datumgrid-oceania proj-datumgrid-world
-
+See: :ref:`transformation_grids`
 
 
 Installing from source
diff --git a/docs/transformation_grids.rst b/docs/transformation_grids.rst
new file mode 100644
index 000000000..69edca6d1
--- /dev/null
+++ b/docs/transformation_grids.rst
@@ -0,0 +1,92 @@
+.. _transformation_grids:
+
+Transformation Grids
+=====================
+
+Transformation grids are necessary when you are performing datum transformations.
+
+More information about the data available is located under the PROJ
+`resource files <https://proj.org/resource_files.html#transformation-grids>`__
+documentation.
+
+`pyproj` API for managing the :ref:`data_directory`
+
+.. warning:: pyproj 2 includes datumgrid 1.8 in the wheels. pyproj 3 will not include any datum grids.
+
+
+Downloading data
+----------------
+
+PROJ 7+
+^^^^^^^^
+
+PROJ 7.0 has introduced, per
+`PROJ RFC 4: Remote access to grids and GeoTIFF grids <https://proj.org/community/rfc/rfc-4.html#rfc4>`__,
+the capability to work with grid files that are not installed on the local machine where PROJ is executed.
+
+Available methods for download include:
+
+- `Mirroing the data <https://proj.org/usage/network.html#mirroring>`__:
+
+  .. code-block:: bash
+
+    aws s3 sync s3://cdn.proj.org $(python -c "import pyproj; print(pyproj.datadir.get_data_dir())")
+
+  .. code-block:: bash
+
+    wget --mirror https://cdn.proj.org/ -P $(python -c "import pyproj; print(pyproj.datadir.get_data_dir())")
+
+- The `projsync <https://proj.org/apps/projsync.html>`__ command line program.
+
+- Enabling `PROJ network <https://proj.org/usage/network.html>`__ capabilities.
+
+- Use `conda <https://conda.io/en/latest/>`__ with the `conda-forge <https://conda-forge.org/>`__ channel:
+
+  .. code-block:: bash
+
+     conda install -c conda-forge proj-data
+
+
+PROJ <= 6
+^^^^^^^^^^
+
+Available methods for download include:
+
+- Download stable from https://download.osgeo.org/proj or latest from https://github.com/OSGeo/proj-datumgrid
+
+- Use `conda <https://conda.io/en/latest/>`__ with the `conda-forge <https://conda-forge.org/>`__ channel:
+
+  .. code-block:: bash
+
+     conda install -c conda-forge proj-datumgrid-europe proj-datumgrid-north-america proj-datumgrid-oceania proj-datumgrid-world
+
+
+What grids to download?
+-----------------------
+
+- Only using the :obj:`pyproj.crs.CRS` or :obj:`pyproj.Geod` classes? Then no grids are needed.
+
+- Have a machine that can hold and extra 500 MB - 1 GB of data? Then downloading all grids shouldn't be an issue.
+
+- Have a machine with limited space, a great network connection, and PROJ 7+? Look into `PROJ network <https://proj.org/usage/network.html>`__ capabilities.
+
+- Have a machine with limited space and want to pre-download files?
+
+  The :class:`pyproj.transformer.TransformerGroup` can assist finding the grids you need to download.
+
+  .. code-block:: python
+
+    >>> from pyproj.transformer import TransformerGroup
+    >>> tg = TransformerGroup("epsg:4326", "+proj=aea +lat_0=50 +lon_0=-154 +lat_1=55 +lat_2=65 +x_0=0 +y_0=0 +datum=NAD27 +no_defs +type=crs +units=m", always_xy=True)
+    UserWarning: Best transformation is not available due to missing Grid(short_name=ntv2_0.gsb, full_name=, package_name=proj-datumgrid-north-america, url=https://download.osgeo.org/proj/proj-datumgrid-north-america-latest.zip, direct_download=True, open_license=True, available=False)
+    f"{operation.grids[0]!r}"
+    >>> tg
+    <TransformerGroup: best_available=False>
+    - transformers: 37
+    - unavailable_operations: 41
+    >>> tg.transformers[0].description
+    'axis order change (2D) + Inverse of NAD27 to WGS 84 (3) + axis order change (2D) + unknown'
+    >>> tg.unavailable_operations[0].name
+    'Inverse of NAD27 to WGS 84 (33) + axis order change (2D) + unknown'
+    >>> tg.unavailable_operations[0].grids[0].url
+    'https://download.osgeo.org/proj/proj-datumgrid-north-america-latest.zip'