Improve the appeal of the landing pages (docs and README)

* Update the Iris README markdown to be consistent with other SciTools projects.
* Gave the package a description (for pypi).
* Minor spruce of the Iris docs layout to include the tagline and the forkme button

README.md

@@ -1,72 +1,102 @@
-Iris
-====
+<h1 align="center">
+  <a href="https://scitools.org.uk/iris/docs/latest/" style="display: block; margin: 0 auto;">
+   <img src="https://raw.githubusercontent.com/pelson/iris/markdown_readme/docs/iris/src/_static/logo_banner.png"
+        style="max-width: 40%;" alt="Iris"></a><br>
+</h1>
 
-[![Join the chat at https://gitter.im/SciTools/iris](https://badges.gitter.im/SciTools/iris.svg)](https://gitter.im/SciTools/iris?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Build Status](https://api.travis-ci.org/repositories/SciTools/iris.svg?branch=master)](https://travis-ci.org/SciTools/iris/branches)
-[![DOI](https://zenodo.org/badge/5312648.svg)](https://zenodo.org/badge/latestdoi/5312648)
-[![Documentation for master branch ](https://img.shields.io/badge/docs-master-blue.svg)](https://scitools-docs.github.io/iris/master/index.html)
+<h4 align="center">
+    Iris is a powerful, easy to use, and community-driven Python library for
+    analysing and visualising Earth science data
+</h4>
 
-(C) British Crown Copyright 2010 - 2018, Met Office
-
-Iris is a powerful, easy to use, community-driven Python library for
-analysing and visualising meteorological and oceanographic data sets.
+<p align="center">
+<!-- https://shields.io/ is a good source of these -->
+<a href="https://anaconda.org/conda-forge/iris">
+<img src="https://img.shields.io/conda/dn/conda-forge/iris.svg"
+     alt="conda-forge downloads" /></a>
+<a href="https://github.com/SciTools/iris/releases">
+<img src="https://img.shields.io/github/tag/SciTools/iris.svg"
+     alt="Latest version" /></a>
+<a href="https://github.com/SciTools/iris/commits/master">
+<img src="https://img.shields.io/github/commits-since/SciTools/iris/latest.svg"
+     alt="Commits since last release" /></a>
+<a href="https://github.com/SciTools/iris/graphs/contributors">
+<img src="https://img.shields.io/github/contributors/SciTools/iris.svg"
+     alt="# contributors" /></a>
+<a href="https://travis-ci.org/SciTools/iris/branches">
+<img src="https://api.travis-ci.org/repositories/SciTools/iris.svg?branch=master"
+     alt="Travis-CI" /></a>
+<a href="https://zenodo.org/badge/latestdoi/5312648">
+<img src="https://zenodo.org/badge/5312648.svg"
+     alt="zenodo" /></a>
+</p>
+<br>
 
+<!-- NOTE: toc auto-generated with https://github.com/frnmst/md-toc:
+   $ md_toc github README.md -i
+-->
 
-Installation
-------------
+<h1>Table of contents</h1>
 
-Provided all of the dependencies are satisfied, Iris can be installed
-using the following command:
+[](TOC)
 
-    python setup.py install
++ [Overview](#overview)
++ [Documentation](#documentation)
++ [Installation](#installation)
++ [Copyright and licence](#copyright-and-licence)
 
-For more detailed instructions, including details of the dependencies,
-please see INSTALL.
+[](TOC)
 
+# Overview
 
-What's new
-----------
+Iris implements a data model based on the [CF conventions](http://cfconventions.org/)
+giving you a powerful, format-agnostic, interface for working with your data.
+It excels when working with multi-dimensional Earth Science data, where tabular
+representations become unwieldy and inefficient.
 
-A discussion of recent changes is given by the
-"What's new" document:
+[CF Standard names](http://cfconventions.org/standard-names.html),
+[units](https://github.com/SciTools/cf_units), and coordinate metadata
+are built-in to Iris, giving you a rich and expressive interface for maintaining
+an accurate representation of your data. Its first-class treatment of data and
+associated metadata, includes:
 
-- http://scitools.org.uk/iris/docs/latest/whatsnew/index.html
+  * aggregations and reductions (min, max, (area-)weighted mean, etc.)
+  * interpolation and regridding (nearest-neighbor, linear, area-weighted, etc.)
+  * operator overloads (``+``, ``-``, ``*``, ``/``, etc.)
+  * merge and concatenate
+  * subsetting and extraction
+  * unit conversion
+  * a visualisation interface based on [matplotlib](https://matplotlib.org/) and
+    [cartopy](https://scitools.org.uk/cartopy/docs/latest/)
 
-If you need complete detail, then please refer to the commit history of
-the Iris project on GitHub:
+A number of file formats are recognised by Iris, including CF-compliant NetCDF, GRIB,
+and PP, and it has a plugin architecture to allow other formats to be added seamlessly.
 
-- https://github.com/SciTools/iris
+Building upon [numpy](http://www.numpy.org/) and [dask](https://dask.pydata.org/en/latest/),
+Iris scales from efficient single-machine workflows right through to multi-core clusters and HPC.
+Interoperability with packages from the wider scientific python ecosystem comes from Iris'
+use of standard numpy/dask arrays as its underlying data storage.
 
 
-Documentation
--------------
+# Documentation
 
-The full documentation for the current release of Iris, including a user guide, example
-code, and gallery, is online at:
-- http://scitools.org.uk/iris/
+The documentation for Iris is available at <https://scitools.org.uk/iris/docs/latest>,
+including a user guide, example code, and gallery.
 
-There is also a documentation build for the latest code in the main GitHub repository at:
-- https://scitools-docs.github.io/iris/master/index.html
-(also similarly for other branches)
+# Installation
 
+The easiest way to install Iris is with [conda](https://conda.io/miniconda.html):
 
-Copyright and licence
----------------------
+    conda install -c conda-forge iris
 
-(C) British Crown Copyright 2010 - 2018, Met Office
+Detailed instructions, including information on installing from source,
+are available in [INSTALL](INSTALL).
 
-This file is part of Iris.
 
-Iris is free software: you can redistribute it and/or modify it under
-the terms of the GNU Lesser General Public License as published by the
-Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
+# Copyright and licence
 
-Iris is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Lesser General Public License for more details.
+Iris may be freely distributed, modified and used commercially under the terms
+of its [GNU LGPLv3 license](COPYING.LESSER).
 
-You should have received a copy of the GNU Lesser General Public License
-along with Iris.  If not, see <http://www.gnu.org/licenses/>.
 
+(C) British Crown Copyright 2010 - 2018, Met Office

docs/iris/src/_templates/index.html

@@ -1,9 +1,10 @@
 {% extends "layout.html" %}
 {% set title = 'Iris documentation homepage' %}
 {% block extrahead %}
+{{ super() }}
 
-<script type="text/javascript" src="_static/jquery.cycle.all.latest.js"></script>
-<script type="text/javascript" src="_static/random_image.js"></script>
+<script type="text/javascript" src="{{ pathto("_static/jquery.cycle.all.latest.js", 1) }}"></script>
+<script type="text/javascript" src="{{ pathto("_static/random_image.js", 1) }}"></script>
 
 <style type="text/css">
 #slideshow { width: 400px; }
@@ -12,6 +13,15 @@
 #sliderNav div { display: inline-block; height: 8px; width: 8px; margin: 0 2px;
   border: #ccc medium solid; border-radius: 50%; box-shadow: 0 0 2px 0 #ccc;}
 #sliderNav div.activeSlide { border-color: #777; background-color: #ccc; }
+
+
+.bodywrapper {
+    width: 100%;
+}
+.sphinxsidebarwrapper {
+    display: none
+}
+
 </style>
 
 <script type="text/javascript">

docs/iris/src/_templates/layout.html

@@ -7,6 +7,9 @@
 
     <link rel="stylesheet" href="{{ pathto('_static/style.css', 1) }}" type="text/css" />
     <script type="text/javascript" src="http://docs.python.org/2/_static/copybutton.js"></script>
+
+    <!-- Nice fonts... -->
+    <link href="https://fonts.googleapis.com/css?family=Alike" rel="stylesheet">
 {% endblock %}
 
 
@@ -19,13 +22,53 @@
 
 
 {% block relbar1 %}
-<div style="background-color: white; text-align: left; padding: 1px 10px 1px 15px">
-<p style="margin-left: 15px; font-weight:bolder; letter-spacing:0.1ex;">
-<a href="{{ pathto('index') }}"><img src="{{pathto("_static/Iris7_1_trim_100.png", 1) }}" width=101 height=100 border="0" style="vertical-align:middle" alt="Logo"/></a>
-<span style="font-size: 400%; vertical-align:middle"> Iris {{version}} </span>
-</p>
 
+
+
+
+<style>
+.github-img {
+  position: absolute;
+  top: 0;
+  right: 80px;
+  border: 0;
+}
+
+/* Take into account the resizing effect of the page (which has a minimum */
+/* width of 740px + 80px margins). */
+@media screen and (max-width: calc(740px + 80px + 80px)) {
+  .github-img {
+    right: calc(100% - 740px - 80px);
+  }
+}
+
+@media screen and (max-width: calc(740px + 80px)) {
+  .github-img {
+    left: calc(740px + 80px - 149px);
+    right: 0px;
+  }
+}
+</style>
+<a href="https://github.com/you">
+    <img class="github-img" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub">
+</a>
+
+
+<div style="background-color: white; text-align: left; padding: 0px; height: 149px;">
+    <a href="{{ pathto("index") }}">
+        <img src="{{ pathto("_static/Iris7_1_trim_100.png", 1) }}" border="0" style="height: 100px; vertical-align: middle; float: left; margin: 20px 2em 0.8em 4%; padding: 0px;" alt="Logo" />
+    </a>
+    <div style="display: inline-block; width: calc(100% - 110px - 2em - 4%);">
+      <h1 style="font-size: 3.5rem; font-family: 'Alike', serif; margin-top: 40px; padding: 0px; color: #323232; padding-bottom: 0.2em;">
+          Iris <span style="font-size: 1.5rem;">v2.1</span>
+      </h1>
+      <h4 style="padding: 0px; max-width: 60ch; margin-top: 0px; margin-bottom: 0px;">
+         a powerful, easy to use, community-driven Python library for analysing and
+         visualising Earth science data
+      </h4>
+    </div>
 </div>
+
 {{ super() }}
 {% endblock %}
 

setup.py

@@ -230,13 +230,19 @@ def extract_version():
 
 pypi_name = 'scitools-iris'
 
+with open(os.path.join(HERE, 'README.md'), 'r') as fh:
+    description = ''.join(fh.readlines())
 
 setup(
     name=pypi_name,
     version=extract_version(),
     url='http://scitools.org.uk/iris/',
     author='UK Met Office',
     author_email='[email protected]',
+    description="A powerful, easy to use, and community-driven Python "
+                "library for analysing and visualising Earth science data",
+    long_description=description,
+    long_description_content_type='text/markdown',
     packages=find_package_tree('lib/iris', 'iris'),
     package_dir={'': 'lib'},
     include_package_data=True,