[ckan#3641] Show specific setuptools version in documentation

doc/.gitignore

@@ -1 +1 @@
-_latest_release.rst
+_substitutions.rst

doc/conf.py

@@ -168,13 +168,24 @@ def latest_package_name(distro='trusty'):
         version=latest_minor_version, distro=distro)
 
 
-def write_latest_release_file():
-    '''Write a file in the doc/ dir containing reStructuredText substitutions
-    for the latest release tag name and version number.
+def min_setuptools_version():
+    '''
+    Get the minimum setuptools version as defined in requirement-setuptools.txt.
+    '''
+    filename = os.path.join(os.path.dirname(__file__), '..',
+                            'requirement-setuptools.txt')
+    with open(filename) as f:
+        return f.read().split('==')[1].strip()
+
+
+def write_substitutions_file(**kwargs):
+    '''
+    Write a file in the doc/ dir containing reStructuredText substitutions.
 
+    Any keyword argument is stored as a substitution.
     '''
-    filename = '_latest_release.rst'
-    template = ''':orphan:
+    filename = '_substitutions.rst'
+    header = ''':orphan:
 
 .. Some common reStructuredText substitutions.
 
@@ -189,22 +200,21 @@ def write_latest_release_file():
 
      |latest_release_version|
 
-.. |latest_release_tag| replace:: {latest_tag}
-.. |latest_release_version| replace:: {latest_version}
-.. |latest_package_name_precise| replace:: {package_name_precise}
-.. |latest_package_name_trusty| replace:: {package_name_trusty}
-
 '''
-    open(filename, 'w').write(template.format(
-        filename=filename,
-        latest_tag=latest_release_tag(),
-        latest_version=latest_release_version(),
-        package_name_precise=latest_package_name('precise'),
-        package_name_trusty=latest_package_name('trusty'),
-        ))
-
-
-write_latest_release_file()
+    with open(filename, 'w') as f:
+        f.write(header.format(filename=filename))
+        for name, substitution in kwargs.items():
+            f.write('.. |{name}| replace:: {substitution}\n'.format(
+                    name=name, substitution=substitution))
+
+
+write_substitutions_file(
+    latest_release_tag=latest_release_tag(),
+    latest_release_version=latest_release_version(),
+    latest_package_name_precise=latest_package_name('precise'),
+    latest_package_name_trusty=latest_package_name('trusty'),
+    min_setuptools_version=min_setuptools_version(),
+)
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation

doc/maintaining/installing/install-from-package.rst

@@ -1,4 +1,4 @@
-.. include:: /_latest_release.rst
+.. include:: /_substitutions.rst
 
 ============================
 Installing CKAN from package

doc/maintaining/installing/install-from-source.rst

@@ -1,4 +1,4 @@
-.. include:: /_latest_release.rst
+.. include:: /_substitutions.rst
 
 ===========================
 Installing CKAN from source
@@ -98,11 +98,11 @@ a. Create a Python `virtual environment <http://www.virtualenv.org>`_
 
        |activate|
 
-b. Make sure ``setuptools`` is up-to-date:
+b. Install the recommended ``setuptools`` version:
 
    .. parsed-literal::
 
-       pip install --upgrade setuptools
+       pip install setuptools==\ |min_setuptools_version|
 
 c. Install the CKAN source code into your virtualenv.
    To install the latest stable release of CKAN (CKAN |latest_release_version|),