Merge pull request #1041 from mwtoews/docs

Rewrite references using BibTeX and sphinxcontrib-bibtex

docs/source/conf.py

@@ -31,6 +31,7 @@
 # ones.
 extensions = [
     'sphinx.ext.mathjax',
+    'sphinxcontrib.bibtex',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/geodesic.rst

@@ -152,10 +152,11 @@ catalog of those cases:
 Background
 ----------
 
-The algorithms implemented by this package are given in [Karney2013]_
-and are based on [Bessel1825]_ and [Helmert1880]_; the algorithm for
-areas is based on [Danielsen1989]_.  These improve on the work of
-[Vincenty1975]_ in the following respects:
+The algorithms implemented by this package are given in :cite:`Karney2013`
+(`addenda <https://geographiclib.sourceforge.io/geod-addenda.html>`_)
+and are based on :cite:`Bessel1825` and :cite:`Helmert1880`; the algorithm for
+areas is based on :cite:`Danielsen1989`.  These improve on the work of
+:cite:`Vincenty1975` in the following respects:
 
 * The results are accurate to round-off for terrestrial ellipsoids (the
   error in the distance is less then 15 nanometers, compared to 0.1 mm
@@ -166,5 +167,8 @@ areas is based on [Danielsen1989]_.  These improve on the work of
   geodesic.  This allows, for example, the area of a geodesic polygon to
   be computed.
 
-Additional background material is provided in [GeodesicBib]_,
-[GeodesicWiki]_, and [Karney2011]_.
+Additional background material is provided in GeographicLib's `geodesic
+bibliography <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_,
+Wikipedia's article "`Geodesics on an ellipsoid
+<https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid>`_", and :cite:`Karney2011`
+(`errata <https://geographiclib.sourceforge.io/geod-addenda.html#geod-errata>`_).

docs/source/operations/projections/calcofi.rst

@@ -82,8 +82,8 @@ Options
 Mathematical definition
 ################################################################################
 
-The algorithm used to make conversions is described in [EberHewitt1979]_ with
-a few corrections reported in [WeberMoore2013]_.
+The algorithm used to make conversions is described in :cite:`EberHewitt1979` with
+a few corrections reported in :cite:`WeberMoore2013`.
 
 
 Further reading

docs/source/operations/projections/cass.rst

@@ -30,7 +30,7 @@ Although the Cassini projection has been largely replaced by the Transverse Merc
 Usage
 #####
 
-There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century [Steers1970]_.
+There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century :cite:`Steers1970`.
 Many of these maps were prepared at a scale of 1:2,500.
 The Cassini-Soldner was also used for the detailed mapping of many German states during the same period.
 
@@ -67,7 +67,7 @@ Options
 Mathematical definition
 #######################
 
-The formulas describing the Cassini projection are taken from Snyder's [Snyder1987]_.
+The formulas describing the Cassini projection are taken from :cite:`Snyder1987`.
 
 :math:`\phi_0` is the latitude of origin that match the center of the map (default to 0). It can be set with ``+lat_0``.
 
@@ -162,5 +162,4 @@ Further reading
 ###############
 
 #. `Wikipedia <https://en.wikipedia.org/wiki/Equirectangular_projection>`_
-#. [Snyder1987]_
 #. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas  <http://www.ihsenergy.com/epsg/guid7.pdf>`_

docs/source/operations/projections/ccon.rst

@@ -39,7 +39,7 @@ conformal.
 
 An example of usage (and the main reason to implement this projection in proj4)
 is the ATPOL geobotanical grid of Poland, developed in Institute of Botany,
-Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]_. The grid was
+Jagiellonian University, Krakow, Poland in 1970s :cite:`Zajac1978`. The grid was
 originally handwritten on paper maps and further copied by hand. The projection
 (together with strange Earth radius) was chosen by its creators as the compromise
 fit to existing maps during first software development in DOS era. Many years later
@@ -51,7 +51,7 @@ The ATPOL coordinates can be achieved with with the following parameters:
 
    +proj=ccon +lat_1=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=-350000
 
-For more information see [Komsta2016]_ and [Verey2017]_.
+For more information see :cite:`Komsta2016` and :cite:`Verey2017`.
 
 Parameters
 ################################################################################

docs/source/operations/projections/eqc.rst

@@ -89,7 +89,7 @@ Parameters
 Mathematical definition
 #######################
 
-The formulas describing the Equidistant Cylindrical projection are all taken from Snyder's [Snyder1987]_.
+The formulas describing the Equidistant Cylindrical projection are all taken from :cite:`Snyder1987`.
 
 :math:`\phi_{ts}` is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set with ``+lat_ts``.
 

docs/source/operations/projections/gall.rst

@@ -69,7 +69,7 @@ Parameters
 Mathematical definition
 #######################
 
-The formulas describing the Gall Stereographical are all taken from Snyder's [Snyder1993]_.
+The formulas describing the Gall Stereographical are all taken from :cite:`Snyder1993`.
 
 Spherical form
 **************

docs/source/operations/projections/merc.rst

@@ -37,7 +37,7 @@ Applications should be limited to equatorial regions, but is frequently
 used for navigational charts with latitude of true scale (:option:`+lat_ts`) specified within
 or near chart's boundaries.
 Often inappropriately used for world maps since the regions near the poles
-cannot be shown [Evenden1995]_.
+cannot be shown :cite:`Evenden1995`.
 
 
 Example using latitude of true scale::
@@ -76,7 +76,7 @@ Parameters
 Mathematical definition
 #######################
 
-The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals [Evenden2005]_.
+The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals :cite:`Evenden2005`.
 
 Spherical form
 **************

docs/source/operations/projections/mill.rst

@@ -32,7 +32,7 @@ Usage
 ########
 
 The Miller Cylindrical projection is used for world maps and in several atlases,
-including the National Atlas of the United States (USGS, 1970, p. 330-331) [Snyder1987]_.
+including the National Atlas of the United States (USGS, 1970, p. 330-331) :cite:`Snyder1987`.
 
 Example using Central meridian 90°W::
 
@@ -55,7 +55,7 @@ Parameters
 Mathematical definition
 #######################
 
-The formulas describing the Miller projection are all taken from Snyder's manuals [Snyder1987]_.
+The formulas describing the Miller projection are all taken from :cite:`Snyder1987`.
 
 
 Forward projection

docs/source/operations/projections/qsc.rst

@@ -36,15 +36,15 @@ It is an equal-area projection, and at the same time introduces only limited ang
 distortions. It treats all cube sides equally, i.e. it does not use different
 projections for polar areas and equatorial areas. These properties make QSC
 projection a good choice for planetary-scale terrain rendering. Map data can be
-organized in quadtree structures for each cube side. See [LambersKolb2012]_ for an example.
+organized in quadtree structures for each cube side. See :cite:`LambersKolb2012` for an example.
 
-The QSC projection was introduced by [ONeilLaubscher1976]_,
-building on previous work by [ChanONeil1975]_. For clarity: The
-earlier QSC variant described in [ChanONeil1975]_ became known as the COBE QSC since it
+The QSC projection was introduced by :cite:`ONeilLaubscher1976`,
+building on previous work by :cite:`ChanONeil1975`. For clarity: The
+earlier QSC variant described in :cite:`ChanONeil1975` became known as the COBE QSC since it
 was used by the NASA Cosmic Background Explorer (COBE) project; it is an approximately
 equal-area projection and is not the same as the QSC projection.
 
-See also [CalabrettaGreisen2002]_ Sec. 5.6.2 and 5.6.3 for a description of both and
+See also :cite:`CalabrettaGreisen2002` Sec. 5.6.2 and 5.6.3 for a description of both and
 some analysis.
 
 In this implementation, the QSC projection projects onto one side of a circumscribed
@@ -65,7 +65,7 @@ cube. The cube side is selected by choosing one of the following six projection
 +-------------------------+--------------------+
 
 Furthermore, this implementation allows the projection to be applied to ellipsoids.
-A preceding shift to a sphere is performed automatically; see [LambersKolb2012]_ for details.
+A preceding shift to a sphere is performed automatically; see :cite:`LambersKolb2012` for details.
 
 
 Usage

docs/source/operations/transformations/deformation.rst

@@ -38,7 +38,7 @@ writes both file formats. Using GDAL for construction of new grids is recommende
 Example
 -------------------------------------------------------------------------------
 
-In [Häkli2016]_ coordinate transformation including a deformation model is described.
+In :cite:`Hakli2016` coordinate transformation including a deformation model is described.
 The paper describes how coordinates from the global ITRFxx frames are transformed to the
 local Nordic realisations of ETRS89. Scandinavia is an area with significant post-glacial
 rebound. The deformations from the post-glacial uplift is not accounted for in the

docs/source/operations/transformations/molodensky.rst

@@ -16,7 +16,7 @@ differences between the semimajor axes and flattening parameters of the referenc
 ellipsoids. Due to its algorithmic simplicity, it was popular prior to the
 ubiquity of digital computers. Today, it is mostly interesting for historical
 reasons, but nevertheless indispensable due to the large amount of data that has
-already been transformed that way [EversKnudsen2017]_.
+already been transformed that way :cite:`EversKnudsen2017`.
 
 +---------------------+----------------------------------------------------------+
 | **Alias**           | molodensky                                               |
@@ -45,7 +45,7 @@ is that it is fairly simple to compute by hand. The ease of computation come at
 cost of limited accuracy.
 
 A derivation of the mathematical formulas for the Molodensky transform can be found
-in [Deakin2004]_.
+in :cite:`Deakin2004`.
 
 
 Examples