Merge lp:~rvb/maas/add-version-switcher into lp:maas/1.4

[Raphaël Badin]

Add the version switcher widget. Add the new `doc-with-versions` make target to generate a version of the documentation that includes the version switcher widget.

This works in conjunction with https://code.launchpad.net/~rvb/maas/multiple-versions-doc-1.6/+merge/214424.

The change to the 1.4 branch should be a one-off. No further modification should be required, even when publishing a new version of the documentation.

If 'add_version_switcher' is set to True, the code in docs/_templates/maas/relations.html dynamically fetches the Javascript file used to generate the version switcher widget from the trunk documentation.

See the result at http://162.213.35.95:8000/docs

[Julian Edwards (julian-edwards)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

 review: approve

Is this any different from the one I just approved? Doesn't look like it.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iEYEARECAAYFAlNCVXYACgkQWhGlTF8G/HeUyQCeOhCAu8iGHAa8/M/25jIfHoPp
4bMAn3sLNslz7tkdE5ktl0eTZ0Qbg2lB
=2lsm
-----END PGP SIGNATURE-----

review: Approve

[Raphaël Badin (rvb)]

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> review: approve
>
> Is this any different from the one I just approved? Doesn't look like it.

Yep, it's the same, just not targeting the same branch.

=== modified file 'Makefile'
--- Makefile	2013-09-03 15:38:39 +0000
+++ Makefile	2014-04-07 17:12:31 +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-07 17:12:31 +0000
+++ docs/_templates/maas/layout.html	2014-04-07 17:12:31 +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 %}

=== modified file 'docs/_templates/maas/relations.html'
--- docs/_templates/maas/relations.html	2014-04-07 17:12:31 +0000
+++ docs/_templates/maas/relations.html	2014-04-07 17:12:31 +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-07 17:12:31 +0000
+++ docs/conf.py	2014-04-07 17:12:31 +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'
 
@@ -240,3 +257,11 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+# 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,
+}
+