RF: use long_description for README.rst

Use script to synchronize README.rst with long description in info.py.

Use long_description for inclusion in docs.

This allows us to put extra github-related cruft at the top of the
README.rst.

Author: matthew-brett

Makefile

@@ -281,5 +281,8 @@ tox-stale:
 	# installed)
 	tox -e python25,python26,python27,python32,np-1.2.1
 
+refresh-readme:
+	$(PYTHON) tools/refresh_readme.py
+
 .PHONY: orig-src pylint
 

README.rst

@@ -1,6 +1,9 @@
 .. -*- rest -*-
 .. vim:syntax=rest
 
+.. Following contents should be from LONG_DESCRIPTION in nibabel/info.py
+
+
 =======
 NiBabel
 =======

doc/source/.gitignore

@@ -0,0 +1 @@
+_long_description.inc

doc/source/conf.py

@@ -34,6 +34,10 @@
 rel = {}
 execfile('../../nibabel/info.py', rel)
 
+# Write long description from info
+with open('_long_description.inc', 'wt') as fobj:
+    fobj.write(rel['LONG_DESCRIPTION'])
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',

doc/source/devel/make_release.rst

@@ -64,8 +64,10 @@ Release checklist
 
 * Check the copyright year in ``doc/source/conf.py``
 
-* Check the ``long_description`` in ``nibabel/info.py``.  Check it matches the
-  ``README`` in the root directory.  Check the output of::
+* Refresh the ``REAMDE.rst`` text from the ``LONG_DESCRIPTION`` in ``info.py``
+  by running ``make refresh_readme``.
+
+  Check the output of::
 
     rst2html.py README.rst > ~/tmp/readme.html
 

doc/source/index.rst

@@ -7,7 +7,7 @@
   #
   ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###
 
-.. include:: ../../README.rst
+.. include:: _long_description.inc
 
 Documentation
 =============

nibabel/info.py

@@ -28,9 +28,11 @@
 
 description  = 'Access a multitude of neuroimaging data formats'
 
-# Note: this long_description is actually a copy/paste from the top-level
-# README.rst, so that it shows up nicely on PyPI.  So please remember to edit
-# it only in one place and sync it correctly.
+# Note: this long_description is the canonical place to edit this text.
+# It also appears in README.rst, but it should get there by running
+# ``tools/refresh_readme.py`` which pulls in this version.
+# We also include this text in the docs by ``..include::`` in
+# ``docs/source/index.rst``.
 long_description = """
 =======
 NiBabel

tools/refresh_readme.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python
+""" Refresh README.rst file from long description
+
+Should be run from nibabel root (containing setup.py)
+"""
+from __future__ import print_function
+
+import os
+
+readme_lines = []
+with open('README.rst', 'rt') as fobj:
+    for line in fobj:
+        readme_lines.append(line)
+        if line.startswith('.. Following contents should be'):
+            break
+    else:
+        raise ValueError('Expected comment not found')
+
+rel = {}
+execfile(os.path.join('nibabel', 'info.py'), rel)
+
+readme = ''.join(readme_lines) + '\n' + rel['LONG_DESCRIPTION']
+
+with open('README.rst', 'wt') as fobj:
+    fobj.write(readme)
+
+print('Done')