Project description content duplication

In multiple locations we provide an almost-identical overview of the library. It should be possible & useful to consolidate some of these descriptions by:

• reducing the duplication of this content across the codebase;
• using consistent Markup format for each such that the release-time updating process is a simple copy/paste job.

Proposal

Here is a summary of the current status of the descriptions in question:

Given the above, I think we can at least remove the hard-codedsetup.py description text for the PyPI description and instead take it from the README. Actually there is detailed guidance on this I have found in a great help page from PyPA. Using that as a guide, it would be something like this (it's a long diff but most is just removing the setting of the long_description variable, so scroll to the bottom where the interesting bit is where it is reassigned to the README contents):

diff --git a/setup.py b/setup.py
index 101f060f4..42a764373 100755
--- a/setup.py
+++ b/setup.py
@@ -96,118 +96,13 @@ class build_umread(build):
 #--- End: class
 
 
-long_description="""
-CF Python
-=========
-
-The Python cf package is an Earth science data analysis library that
-is built on a complete implementation of the CF data model
-
-
-Documentation
-=============
-
-http://ncas-cms.github.io/cf-python
-
-Tutorial
-========
-
-https://ncas-cms.github.io/cf-python/tutorial
-
-Installation
-============
-
-http://ncas-cms.github.io/cf-python/installation
-
-
-Functionality
-=============
-
-The `cf` package implements the CF data model
-(https://doi.org/10.5194/gmd-10-4619-2017) for its internal data
-structures and so is able to process any CF-compliant dataset. It is
-not strict about CF-compliance, however, so that partially conformant
-datasets may be ingested from existing datasets and written to new
-datasets. This is so that datasets which are partially conformant may
-nonetheless be modified in memory.
-
-The `cf` package can:
-
-* read field constructs from netCDF, PP and UM datasets,
-
-* create new field constructs in memory,
-
-* write field constructs to netCDF datasets on disk,
-
-* read, write, and create coordinates defined by geometry cells.
-
-* read netCDF and CDL datasets containing hierarchical groups,
-
-* inspect field constructs,
-
-* test whether two field constructs are the same,
-
-* modify field construct metadata and data,
-
-* create subspaces of field constructs,
-
-* incorporate, and create, metadata stored in external files,
-
-* read, write, and create data that have been compressed by convention
-  (i.e. ragged or gathered arrays), whilst presenting a view of the
-  data in its uncompressed form,
-
-* combine field constructs arithmetically,
-
-* manipulate field construct data by arithmetical and trigonometrical
-  operations,
-
-* perform statistical collapses on field constructs,
-
-* perform histogram, percentile and binning operations on field
-  constructs,
-
-* regrid field constructs,
-
-* apply convolution filters and moving means to field constructs,
-
-* calculate derivatives of field constructs,
-
-* create field constructs to create derived quantities (such as
-  vorticity).
-
-
-Visualization
-=============
-
-Powerful, flexible, and very simple to produce visualizations of field
-constructs are available with the `cfplot` package
-(http://ajheaps.github.io/cf-plot), that needs to be installed
-seprately to the `cf` package.
-
-See the `cfplot` gallery (http://ajheaps.github.io/cf-plot/gallery.html)
-for the full range range plotting possibilities with example code.
-
-
-Command line utilities
-======================
-
-During installation the ``cfa`` command line utility is also
-installed, which
-
-* generates text descriptions of field constructs contained in files,
-  and
-
-* creates new datasets aggregated from existing files.
-
-
-Tests
-=====
-
-Tests are run from within the ``cf/test`` directory:
-
-    python run_tests.py
-"""
+# Get contents of the README file to use as the long description for e.g. PyPI
+# relying on long_description_content_type='text/markdown' (see
+# https://packaging.python.org/guides/making-a-pypi-friendly-readme/).
+repo_root_directory = os.path.abspath(os.path.dirname(__file__))
+with open(
+        os.path.join(repo_root_directory, 'README.md'), encoding='utf-8') as f:
+    long_description = f.read()
 
 # Get dependencies
 requirements = open('requirements.txt', 'r')
@@ -215,6 +110,7 @@ install_requires = requirements.read().splitlines()
 
 setup(name = "cf-python",
       long_description = long_description,
+      long_description_content_type = 'text/markdown',
       version      = version,
       description  = "A CF-compliant earth science data analysis library",
       author       = "David Hassell",

Questions

@davidhassell instead of going ahead straight away with the above as in the diff I would like to ask:

1. if there is not some reason we do not do that currently, in case it means it is not a good idea;
2. whether we might also want to consider converting the README.md into a README.rst so that all of the descriptions will be in RST format, making it trivial to use the same in each location.

Start by reading the duplicated description sources in setup.py, README.md, cf/init.py, and the documentation root Introduction page, then compare the PyPA guidance linked in the issue. Determine which source and markup format the project will adopt, and verify that the PyPI description and documentation still render correctly after the duplication is reduced.