diff options
| -rw-r--r-- | HOWTO-RELEASE | 2 | ||||
| -rw-r--r-- | docs/source/conf.py | 17 | ||||
| -rw-r--r-- | docs/source/install.rst | 77 | ||||
| -rw-r--r-- | docs/source/resource_files.rst | 19 |
4 files changed, 88 insertions, 27 deletions
diff --git a/HOWTO-RELEASE b/HOWTO-RELEASE index 1f140bfe..a9a17e69 100644 --- a/HOWTO-RELEASE +++ b/HOWTO-RELEASE @@ -63,7 +63,7 @@ Update the following files with the new ABI version number: Man pages are (mostly) automatically generated from the Sphinx docs. Follow these steps: - - Temporarily update version in `docs/source/conf.py` + - Temporarily update `version` and `data_version` in `docs/source/conf.py` - run `scripts/update_man.sh` - Revert version number in `docs/source/conf.py` diff --git a/docs/source/conf.py b/docs/source/conf.py index c37e7e17..e85e5dfb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -69,6 +69,7 @@ copyright = u'1983-{0}'.format(now.year) # |version| and |release|, also used in various other places throughout the # built documents. version = '7.1.0' +data_version = '1.0' # use same |release| as |version| release = version @@ -120,6 +121,22 @@ highlight_language = 'none' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False +# Replacement macros for use in code-blocks etc. With inspiration from +# https://github.com/sphinx-doc/sphinx/issues/4054#issuecomment-329097229 +def replace_words(app, docname, source): + result = source[0] + for key in app.config.replacements: + result = result.replace(key, app.config.replacements[key]) + source[0] = result + +replacements = { + "{PROJVERSION}" : "{version_number}".format(version_number=version), + "{PROJDATAVERSION}" : "{data_version_number}".format(data_version_number=data_version), +} + +def setup(app): + app.add_config_value('replacements', {}, True) + app.connect('source-read', replace_words) # -- Options for HTML output ---------------------------------------------- diff --git a/docs/source/install.rst b/docs/source/install.rst index d8daa3a9..f6ca0d5d 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -26,13 +26,14 @@ from the ``conda-forge`` channel:: conda install -c conda-forge proj -Using ``conda`` you can also install the PROJ grid packages. Here's how to install -the `proj-datumgrid-europe` package:: +Using ``conda`` you can also install the PROJ data package. Here's how to install +the `proj-data` package:: - conda install -c conda-forge proj-datumgrid-europe + conda install -c conda-forge proj-data -Available is also the ``proj-datumgrid-north-america``, ``proj-datumgrid-oceania`` -and ``proj-datumgrid-world``. +Available is also the legacy packages ``proj-datumgrid-europe``, +``proj-datumgrid-north-america``, ``proj-datumgrid-oceania`` and +``proj-datumgrid-world``. .. tip:: Read more about the various datumgrid packages available :ref:`here<datumgrid>`. @@ -129,9 +130,6 @@ Compilation and installation from source code The classic way of installing PROJ is via the source code distribution. The most recent version is available from the :ref:`download page<current_release>`. -You will need that and at least the standard *proj-datumgrid* package for a -successful installation. - The following guides show how to compile and install the software using the Autotools and CMake build systems. @@ -157,7 +155,7 @@ FSF's configuration procedure is used to ease installation of the PROJ system. The default destination path prefix for installed files is ``/usr/local``. Results from the installation script will be placed into subdirectories ``bin``, -``include``, ``lib``, ``man/man1`` and ``man/man3``. If this default path prefix +``include``, ``lib``, and ``man/man1``. If this default path prefix is proper, then execute:: ./configure @@ -175,17 +173,7 @@ If you are building from the git repository you have to first run:: which will generate a configure script that can be used as described above. -Before proceeding with the installation we need to add the datum grids. Unzip -the contents of the *proj-datumgrid* package into ``data/``:: - - unzip proj-datumgrid-1.7.zip -d proj-5.0.1/data/ - -The installation will automatically move the grid files to the correct location. -Alternatively the grids can be installed manually in the directory pointed to -by the :envvar:`PROJ_LIB` environment variable. The default location is -``/usr/local/share/proj``. - -With the grid files in place we can now build and install PROJ:: +With the data files in place we can now build and install PROJ:: make make install @@ -196,8 +184,27 @@ Tests are run with:: make check -The test suite requires that the proj-datumgrid package is installed in -:envvar:`PROJ_LIB`. +With a successful install of PROJ we can now install data files using the +:program:`projsync` utility:: + + projsync --system-directory + +which will download all resource files currently available for PROJ. If less than +the entire collection of resource files is needed the call to :program:`projsync` +can be modified to suit the users needs. See :ref:`projsync` for more options. + +.. note:: + + The use of :program:`projsync` requires that network support is enabled (the + default option). If the resource files are not installed using + :program:`projsync` PROJ will attempt to fetch them automatically when a + transformation needs a specific data file. This requires that + :envvar:`PROJ_NETWORK` is set to ``ON``. + + As an alternative on systems where network access is disabled, the + :ref:`proj-data <datumgrid>` + package can be downloaded and added to the :envvar:`PROJ_LIB` directory. + Autotools configure options @@ -252,7 +259,7 @@ With the CMake build system you can compile and install PROJ on more or less any platform. After unpacking the source distribution archive step into the source- tree:: - cd proj-5.0.1 + cd proj-{PROJVERSION} Create a build directory and step into it:: @@ -282,8 +289,28 @@ Tests are run with:: ctest -The test suite requires that the proj-datumgrid package is installed -in :envvar:`PROJ_LIB`. +With a successful install of PROJ we can now install data files using the +:program:`projsync` utility:: + + projsync --system-directory + +which will download all resource files currently available for PROJ. If less than +the entire collection of resource files is needed the call to :program:`projsync` +can be modified to suit the users needs. See :ref:`projsync` for more options. + +.. note:: + + The use of :program:`projsync` requires that network support is enabled (the + default option). If the resource files are not installed using + :program:`projsync` PROJ will attempt to fetch them automatically when a + transformation needs a specific data file. This requires that + :envvar:`PROJ_NETWORK` is set to ``ON``. + + As an alternative on systems where network access is disabled, the + :ref:`proj-data <datumgrid>` + package can be downloaded and added to the :envvar:`PROJ_LIB` directory. + + CMake configure options diff --git a/docs/source/resource_files.rst b/docs/source/resource_files.rst index 39de6057..19dab1b4 100644 --- a/docs/source/resource_files.rst +++ b/docs/source/resource_files.rst @@ -123,10 +123,27 @@ all formats. Using GDAL for construction of new grids is recommended. External resources and packaged grids ------------------------------------------------------------------------------- +proj-data ++++++++++ + +The ``proj-data`` package is a collection of all the resource files that are +freely available for use with PROJ. The package is maintained on +`GitHub <https://github.com/OSGeo/PROJ-data>`_ and the contents of the package +are show-cased on the `PROJ CDN <https://cdn.proj.org/>`_. The contents of the +package can be installed using the :program:`projsync` package or by downloading +the zip archive of the package and unpacking in the :envvar:`PROJ_LIB` directory. + proj-datumgrid ++++++++++++++ -For a functioning PROJ, installation of the +.. note:: + + The packages described below can be used with PROJ 7 and later but are + primarily meant to be used with PROJ 6 and earlier versions. The proj-datumgrid + series of packages are not maintained anymore and are only kept available for + legacy purposes. + +For a functioning builds of PROJ prior to version 7, installation of the `proj-datumgrid <https://github.com/OSGeo/proj-datumgrid>`_ is needed. If you have installed PROJ from a package system chances are that this will already be done for you. The *proj-datumgrid* package provides transformation grids that |