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

[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.5 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

Nice work Raphers! Just a question and a suggestion:

On 07/04/14 02:32, Raphaël Badin wrote:
> Raphaël Badin has proposed merging
> lp:~rvb/maas/add-version-switcher-1.5 into lp:maas/1.5.
>
> Commit message: 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.

Is there a reason to make this conditional?

> This works in conjunction with
> https://code.launchpad.net/~rvb/maas/multiple-versions-doc-1.6/+merge/214424.
>
> The change to the 1.5 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
>

I think it would look better if you could put the switcher at the top
somewhere so that it's more prominent. Also, its title should be
"Documentation for MAAS version:"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iEYEARECAAYFAlNCVUAACgkQWhGlTF8G/Hc9CQCdESXPX3wM1L41K9GXftUY5Xiw
0asAn1po0JklTowRClocmJarUHRTm9P8
=yGGO
-----END PGP SIGNATURE-----

review: Approve

[Raphaël Badin (rvb)]

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> review: approve
>
> Nice work Raphers! Just a question and a suggestion:
>
> On 07/04/14 02:32, Raphaël Badin wrote:
> > Raphaël Badin has proposed merging
> > lp:~rvb/maas/add-version-switcher-1.5 into lp:maas/1.5.
> >
> > Commit message: 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.
>
> Is there a reason to make this conditional?

Yes, I want to keep a way to generate the documentation *without* the version switcher widget. This is the documentation we will someday package in a maas-doc package.

> I think it would look better if you could put the switcher at the top
> somewhere so that it's more prominent. Also, its title should be
> "Documentation for MAAS version:"

Okay, I'll that.

[Raphaël Badin (rvb)]

> > I think it would look better if you could put the switcher at the top
> > somewhere so that it's more prominent. Also, its title should be
> > "Documentation for MAAS version:"
>
> Okay, I'll do that.

I moved the widget at the top… but I left the title as is since "Documentation for MAAS version:" really doesn't fit (it takes two lines and it's ugly).

[Julian Edwards (julian-edwards)]

On 08/04/14 03:37, Raphaël Badin wrote:
>
>>> I think it would look better if you could put the switcher at the top
>>> somewhere so that it's more prominent. Also, its title should be
>>> "Documentation for MAAS version:"
>>
>> Okay, I'll do that.
>
> I moved the widget at the top… but I left the title as is since "Documentation for MAAS version:" really doesn't fit (it takes two lines and it's ugly).
>
>

Please, the title needs to change, make the text smaller if you have to.

"Version" doesn't mean much on its own like that. "Version what?" was
my first thought, especially when I clicked on it it was initially empty
and only loaded later. Maybe its default values should say "loading...".

=== modified file 'Makefile'
--- Makefile	2014-03-27 04:02:16 +0000
+++ Makefile	2014-04-07 17:12:29 +0000
@@ -164,6 +164,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	2013-12-06 15:11:12 +0000
+++ docs/_templates/maas/layout.html	2014-04-07 17:12:29 +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	2013-12-06 15:11:12 +0000
+++ docs/_templates/maas/relations.html	2014-04-07 17:12:29 +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-03-05 22:17:59 +0000
+++ docs/conf.py	2014-04-07 17:12:29 +0000
@@ -22,6 +22,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,
+}
+