Merge lp:~rvb/maas/version-switcher-1.3 into lp:maas/1.3

[Raphaël Badin]

Backport 2258: Add the bzr last revision, last revision date, and build date to the documentation pages.
Backport 2238: Add version switcher.

This only affects the documentation (i.e. not part of what gets packaged).

[Raphaël Badin (rvb)]

Simple backport, self-approving.

review: Approve

=== modified file 'Makefile'
--- Makefile	2012-11-22 23:39:27 +0000
+++ Makefile	2014-04-14 07:56:25 +0000
@@ -139,6 +139,9 @@
 doc: bin/sphinx docs/api.rst
 	bin/sphinx
 
+doc-with-versions: bin/sphinx
+	cd docs/_build; make SPHINXOPTS="-A add_version_switcher=true" html
+
 man: $(patsubst docs/man/%.rst,man/%,$(wildcard docs/man/*.rst))
 
 man/%: docs/man/%.rst | bin/sphinx-build
 
=== modified file 'docs/_templates/maas/layout.html'
--- docs/_templates/maas/layout.html	2014-04-14 07:56:25 +0000
+++ docs/_templates/maas/layout.html	2014-04-14 07:56:25 +0000
@@ -5,6 +5,7 @@
 <a style="border:0" title="MAAS Documentation Homepage" href="{{ pathto('index.html', 1) }}"><img src="{{ pathto('_static/maas-logo-200.png',1) }}" alt="MAAS logo"/></a>
 <h2 style="text-align:center;">MAAS</h2>
 <p style="font-style:italic;font-size:0.9em; text-align:center; margin-bottom:1.5em">Metal As A Service.</p>
+<span id="version_switcher"></span>
 <br/>
 <br/>
 {% endblock %}
@@ -13,7 +14,12 @@
 <footer class="global clearfix">
   <div class="legal clearfix">
     <p>&copy; Copyright {{ copyright }}. Ubuntu and Canonical are registered trademarks of
-      <a href="http://canonical.com">Canonical Ltd</a></p>
+      <a href="http://canonical.com">Canonical Ltd</a>.
+    </p>
+    <p>
+      Revision {{ bzr_last_revision_number}} ({{ bzr_last_revision_date }}).
+      Documentation generation date: {{ bzr_build_date }}.
+    </p>
   </div>
 </footer>
 {%- endblock %}
 
=== modified file 'docs/_templates/maas/relations.html'
--- docs/_templates/maas/relations.html	2014-04-14 07:56:25 +0000
+++ docs/_templates/maas/relations.html	2014-04-14 07:56:25 +0000
@@ -1,3 +1,15 @@
+<script type="text/javascript">
+$(document).ready(function () {
+  if ({{ add_version_switcher }}) {
+    $.ajaxSetup({cache: true});
+    $.getScript('{{ versions_json_path }}', function() {
+      console.log( "Versions script loaded." );
+      set_up_version_switcher('#version_switcher', '{{ doc_prefix }}');
+    });
+}
+});
+</script>
+
 <h3>Related Topics</h3>
 <ul>
   <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul>
 
=== modified file 'docs/conf.py'
--- docs/conf.py	2014-04-14 07:56:25 +0000
+++ docs/conf.py	2014-04-14 07:56:25 +0000
@@ -23,6 +23,23 @@
 
 # -- General configuration -----------------------------------------------------
 
+# Add a widget to switch between different versions of the documentation to
+# each generated page.
+add_version_switcher = False
+
+# In order for the version widget to be able to redirect correctly to the
+# other versions of the documentation, each version of the documentation
+# has to be accessible at the following addresses:
+# /<doc_prefix>/ -> documentation for trunk.
+# /<doc_prefix>1.4/ ->  documentation for 1.4.
+# etc.
+doc_prefix = 'docs'
+
+# Path of the JSON document, relative to homepage of the documentation for trunk
+# (i.e. '/<doc_prefix>/'), with the list of the versions to include in the
+# version switcher widget.
+versions_path = '_static/versions.js'
+
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
@@ -58,9 +75,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '12.10'
+version = '1.3'
 # The full version, including alpha/beta/rc tags.
-release = '12.10b'
+release = '1.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -240,3 +257,20 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+# Gather information about the branch and the build date.
+from subprocess import check_output
+bzr_last_revision_number = check_output(['bzr', 'revno'])
+bzr_last_revision_date = check_output(['bzr', 'version-info', '--template={date}', '--custom'])
+bzr_build_date = check_output(['bzr', 'version-info', '--template={build_date}', '--custom'])
+
+# Populate html_context with the variables used in the templates.
+html_context = {
+    'add_version_switcher': 'true' if add_version_switcher else 'false',
+    'versions_json_path': '/'.join(['', doc_prefix, versions_path]),
+    'doc_prefix': doc_prefix,
+    'bzr_last_revision_date': bzr_last_revision_date,
+    'bzr_last_revision_number': bzr_last_revision_number,
+    'bzr_build_date': bzr_build_date,
+}
+