[#1380] Encourage installing latest release in source install docs

Needed an automated way to get the latest version number, so I added
functions to doc/conf.py for this, and then used them in the source and
package install docs.

doc/.gitignore

@@ -0,0 +1 @@
+_latest_release.rst

doc/conf.py

@@ -14,7 +14,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+import subprocess
 
 # If your extensions (or modules documented by autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -106,6 +108,92 @@
 # The full version, including alpha/beta/rc tags.
 release = ckan.__version__
 
+
+def latest_release_tag():
+    '''Return the name of the git tag for the latest stable release.
+
+    e.g.: "ckan-2.1.1"
+
+    This requires git to be installed.
+
+    '''
+    git_tags = subprocess.check_output(['git', 'tag', '-l']).split()
+
+    # FIXME: We could do more careful pattern matching against ckan-X.Y.Z here.
+    release_tags = [tag for tag in git_tags if tag.startswith('ckan-')]
+
+    # git tag -l prints out the tags in the right order anyway, but don't rely
+    # on that, sort them again here for good measure.
+    release_tags.sort()
+
+    return release_tags[-1]
+
+
+def latest_release_version():
+    '''Return the version number of the latest stable release.
+
+    e.g. "2.1.1"
+
+    '''
+    version = latest_release_tag()[len('ckan-'):]
+
+    # TODO: We could assert here that latest_version matches X.Y.Z.
+
+    return version
+
+
+def latest_package_name():
+    '''Return the filename of the Ubuntu package for the latest stable release.
+
+    e.g. "python-ckan_2.1_amd64.deb"
+
+    '''
+    # We don't create a new package file name for a patch release like 2.1.1,
+    # instead we just update the existing 2.1 package. So package names only
+    # have the X.Y part of the version number in them, not X.Y.Z.
+    latest_minor_version = latest_release_version()[:3]
+
+    return 'python-ckan_{version}_amd64.deb'.format(
+        version=latest_minor_version)
+
+
+def write_latest_release_file():
+    '''Write a file in the doc/ dir containing reStructuredText substitutions
+    for the latest release tag name and version number.
+
+    '''
+    filename = '_latest_release.rst'
+    template = ''':orphan:
+
+.. Some common reStructuredText substitutions.
+
+   **This file is autogenerated!** So don't edit it by hand.
+
+   You can include this file at the top of your ``*.rst`` file with a line
+   like::
+
+     .. include:: {filename}
+
+   Then use the substitutions in this file, e.g.::
+
+     |latest_release_version|
+
+.. |latest_release_tag| replace:: {latest_tag}
+.. |latest_release_version| replace:: {latest_version}
+.. |latest_package_name| replace:: {package_name}
+
+'''
+    open('_latest_release.rst', 'w').write(template.format(
+        filename=filename,
+        latest_tag=latest_release_tag(),
+        latest_version=latest_release_version(),
+        package_name=latest_package_name(),
+        ))
+
+
+write_latest_release_file()
+
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None

doc/install-from-package.rst

@@ -1,3 +1,5 @@
+.. include:: _latest_release.rst
+
 ============================
 Installing CKAN from package
 ============================
@@ -24,18 +26,22 @@ CKAN:
 
     sudo apt-get install -y nginx apache2 libapache2-mod-wsgi libpq5
 
-#. Download the CKAN package::
+#. Download the CKAN package:
+
+   .. parsed-literal::
 
-    wget http://packaging.ckan.org/python-ckan_2.0_amd64.deb
+      wget \http://packaging.ckan.org/|latest_package_name|
 
    .. note:: If ``wget`` is not present, you can install it
        via::
 
         sudo apt-get install wget
 
-#. Install the CKAN package::
+#. Install the CKAN package:
+
+   .. parsed-literal::
 
-    sudo dpkg -i python-ckan_2.0_amd64.deb
+      sudo dpkg -i |latest_package_name|
 
 .. note:: If you get the following error it means that for some reason the
  Apache WSGI module was not enabled::

doc/install-from-source.rst

@@ -1,3 +1,5 @@
+.. include:: _latest_release.rst
+
 ===========================
 Installing CKAN from source
 ===========================
@@ -90,19 +92,27 @@ a. Create a Python `virtual environment <http://www.virtualenv.org>`_
 
        |activate|
 
-b. Install the CKAN source code into your virtualenv. To install the latest
-   development version of CKAN (the most recent commit on the master branch of
-   the CKAN git repository), run:
+b. Install the CKAN source code into your virtualenv.
+   To install the latest stable release of CKAN (CKAN |latest_release_version|),
+   run:
 
    .. parsed-literal::
 
-       pip install -e 'git+\ |git_url|\#egg=ckan'
+      pip install -e 'git+\ |git_url|\@\ |latest_release_tag|\#egg=ckan'
 
-   Alternatively, to install a specific version such as CKAN 2.0 run:
+   If you're installing CKAN for development, you may want to install the
+   latest development version (the most recent commit on the master branch of
+   the CKAN git repository). In that case, run this command instead:
 
    .. parsed-literal::
 
-       pip install -e 'git+\ |git_url|\@ckan-2.0#egg=ckan'
+       pip install -e 'git+\ |git_url|\#egg=ckan'
+
+   .. warning::
+
+      The development version may contain bugs and should not be used for
+      production websites! Only install this version if you're doing CKAN
+      development.
 
 c. Install the Python modules that CKAN requires into your virtualenv: