From ede2d4b149872f916d254c271920c0631ddf8f97 Mon Sep 17 00:00:00 2001
From: Phil Elson <pelson.pub@gmail.com>
Date: Mon, 21 May 2018 17:40:30 +0100
Subject: [PATCH] Updated the readme to use markdown. Added an example to the
 readme.

---
 README.md  | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.rst | 34 ---------------------
 setup.py   |  5 ++--
 3 files changed, 90 insertions(+), 37 deletions(-)
 create mode 100644 README.md
 delete mode 100644 README.rst

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..1f83f3b8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+<h1 align="center" style="margin:1em;">
+  <a href="https://scitools.org.uk/cf_units/docs/latest/">cf_units</a>
+</h1>
+
+<h4 align="center">
+Units of measure as defined by the Climate and Forecast (CF) metadata
+conventions.
+</h4>
+
+<p align="center">
+<!-- https://shields.io/ is a good source of these -->
+<a href="https://anaconda.org/conda-forge/cf_units">
+<img src="https://img.shields.io/conda/dn/conda-forge/cf_units.svg"
+ alt="conda-forge downloads" /></a>
+<a href="https://github.com/SciTools/cf_units/releases">
+<img src="https://img.shields.io/github/tag/SciTools/cf_units.svg"
+ alt="Latest version" /></a>
+<a href="https://github.com/SciTools/cf_units/commits/master">
+<img src="https://img.shields.io/github/commits-since/SciTools/cf_units/latest.svg"
+ alt="Commits since last release" /></a>
+<a href="https://github.com/SciTools/cf_units/graphs/contributors">
+<img src="https://img.shields.io/github/contributors/SciTools/cf_units.svg"
+ alt="# contributors" /></a>
+<a href="https://travis-ci.org/SciTools/cf_units/branches">
+<img src="https://api.travis-ci.org/repositories/SciTools/cf_units.svg?branch=master"
+ alt="Travis-CI" /></a>
+<!-- <a href="https://zenodo.org/badge/latestdoi/5282596">
+<img src="https://zenodo.org/badge/5282596.svg"
+ alt="zenodo" /></a> -->
+</p>
+<br>
+
+# Table of contents
+
+<!--
+NOTE: toc auto-generated with https://github.com/jonschlinkert/markdown-toc
+    $> markdown-toc -i --bullets='-' README.md
+
+NOTE: This entire README can be markdown linted with
+    https://github.com/igorshubovych/markdownlint-cli
+    $ echo '{"no-inline-html": false}' > .markdownrc
+    $ markdownlint README.md
+-->
+
+<!-- toc -->
+
+- [Overview](#overview)
+  - [Example](#example)
+- [Get in touch](#get-in-touch)
+- [License and copyright](#license-and-copyright)
+
+<!-- tocstop -->
+
+## Overview
+
+Units of measure as required by the Climate and Forecast (CF) metadata
+conventions.
+
+Provision of a wrapper class to support Unidata/UCAR UDUNITS-2 library, and the
+cftime calendar functionality.
+
+Documentation can be found at <https://scitools.org.uk/cf_units/docs/latest/>.
+
+### Example
+
+    >>> from cf_units import Unit
+    >>> km = Unit('kilometers')
+    >>> m = Unit('meters')
+    >>> m.convert(1500, km)
+    1.5
+
+## Get in touch
+
+- Questions, ideas, general discussion or announcements
+  of related projects use the
+  [Google Group](https://groups.google.com/forum/#!forum/scitools-iris).
+- Report bugs, suggest features or view the source code on
+  [GitHub](https://github.com/SciTools/cf_units).
+
+## License and copyright
+
+Cartopy is licensed under GNU Lesser General Public License (LGPLv3).
+
+Development occurs on GitHub at <https://github.com/SciTools/cf_units>, with a
+contributor's license agreement (CLA) that can be found at
+<https://scitools.org.uk/governance.html>.
+
+(C) British Crown Copyright, Met Office
diff --git a/README.rst b/README.rst
deleted file mode 100644
index d18e5c76..00000000
--- a/README.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-cf\_units
-=========
-
-|Travis|_ |Coveralls|_
-
-\(C) British Crown Copyright 2015 - 2018, Met Office
-
-Introduction
-------------
-Units of measure as required by the Climate and Forecast (CF) metadata
-conventions.
-
-Provision of a wrapper class to support Unidata/UCAR UDUNITS-2, and the
-netcdftime calendar functionality.
-
-
-Code
-----
-cf_units is licenced under the GNU Lesser General Public License (LGPLv3).
-The full text of the licence can be found in the COPYING and COPYING.LESSER
-files.
-
-See also
---------
-
-* Development occurs at https://github.com/SciTools/cf_units.
-* Documentation for cf_units can be found at http://scitools.org.uk/cf_units/index.html.
-* The library wrapped by cf_units: `UDUNITS-2 <http://www.unidata.ucar.edu/software/udunits>`_.
-
-.. |Travis| image:: https://travis-ci.org/SciTools/cf_units.svg?branch=master
-.. _Travis: https://travis-ci.org/SciTools/cf_units
-
-.. |Coveralls| image:: https://coveralls.io/repos/github/SciTools/cf_units/badge.svg?branch=master
-.. _Coveralls: https://coveralls.io/github/SciTools/cf_units?branch=master
diff --git a/setup.py b/setup.py
index 76325fd1..b893f087 100644
--- a/setup.py
+++ b/setup.py
@@ -47,8 +47,6 @@ def read(*parts):
                         libraries=['udunits2'],
                         **extra_extension_args)
 
-long_description = '{}'.format(read('README.rst'))
-
 cmdclass = {'build_ext': build_ext}
 cmdclass.update(versioneer.get_cmdclass())
 
@@ -62,7 +60,8 @@ def read(*parts):
     url='https://github.com/SciTools/{}'.format(NAME),
     author='Met Office',
     description='Units of measure as required by the Climate and Forecast (CF) metadata conventions',
-    long_description='{}'.format(read('README.rst')),
+    long_description='{}'.format(read('README.md')),
+    long_description_content_type='text/markdown',
     packages=find_packages(),
     package_data={'cf_units': list(file_walk_relative('cf_units/etc',
                                                       remove='cf_units/'))},