Maintain separate docs for different releases

This will cause CI to build docs for specific branches when they are
pushed to, and to copy the result into a subdirectory of the docs/
directory, instead of the root. The task will also update a
"versions.json" file, for the pages to be able to display/select other
versions.

The doc template is changed slightly to display a select field on top
of the quick search, using some js to fill the versions from the
generated versions.json file, and to change url when a different version
is selected.

This has been tested with a local server, trying to emulate the doc
structure, but the CI part hasn't been really tested.

Known Issues:

- the version.json file contains all versions configured to build, but
  the doc for these might not have been generated yet, which would
  result in 404 errors.
- the logic doesn't know if the current page of the doc exists for the
  selectable versions, so this will also result in 404 errors when
  switching to a version that didn't have the current doc page..
- the url manipulation logic is a bit dirty, as it assumes that the path
  is always of the form of /docs/<version>/….
- theming could certainly be slightly improved.

.travis.yml

@@ -3,6 +3,7 @@ env:
     - KIVY_USE_SETUPTOOLS=1
     - KIVY_SPLIT_EXAMPLES=1
     - SERVER_IP=159.203.106.198
+    - DOC_VERSIONS="stable-1.9.0 stable-1.10 stable master"
 matrix:
   fast_finish: true
   include:
@@ -283,11 +284,17 @@ script:
 
 
 after_success:
-  - if [ "${TRAVIS_OS_NAME}" == "linux" ] && [ "${RUN}" == "docs" ] && [ "${TRAVIS_PULL_REQUEST}" == "false" ] && [ "${TRAVIS_BRANCH}" == "master" ]; then
-      openssl aes-256-cbc -K $encrypted_675f1a0c317c_key -iv $encrypted_675f1a0c317c_iv -in ./kivy/tools/travis/id_rsa.enc -out ~/.ssh/id_rsa -d;
-      chmod 600 ~/.ssh/id_rsa;
-      echo -e "Host $SERVER_IP\n\tStrictHostKeyChecking no\n" >> ~/.ssh/config;
-      rsync --delete --force -r -e "ssh -p 2457" ./doc/build/html/ root@$SERVER_IP:/web/docs/;
+  - if [ "${TRAVIS_OS_NAME}" == "linux" ] && [ "${RUN}" == "docs" ] && [ "${TRAVIS_PULL_REQUEST}" == "false" ]; then
+      for version in $DOC_VERSIONS; do
+        if [ $version == ${TRAVIS_BRANCH} ]; then
+          openssl aes-256-cbc -K $encrypted_675f1a0c317c_key -iv $encrypted_675f1a0c317c_iv -in ./kivy/tools/travis/id_rsa.enc -out ~/.ssh/id_rsa -d;
+          chmod 600 ~/.ssh/id_rsa;
+          echo -e "Host $SERVER_IP\n\tStrictHostKeyChecking no\n" >> ~/.ssh/config;
+          echo "[$(echo $DOC_VERSIONS|tr ' ' ', '|sed -s 's/\([^,]\+\)/"\1"/g')]" > versions.json
+          rsync --force -e "ssh -p 2457" versions.json root@$SERVER_IP:/web/docs/;
+          rsync --delete --force -r -e "ssh -p 2457" ./doc/build/html/ root@$SERVER_IP:/web/docs/$version;
+        fi;
+      done;
     fi;
 
 notifications:

doc/sources/.static/fresh.css

@@ -485,3 +485,12 @@ div.navlink {
 	top: -30px;
 	height: 0px;
 }
+
+#version_selector {
+	width: 100%;
+	-webkit-appearance: none;
+	-moz-appearance: none;
+	border: 1px solid #d0d0d0;
+	padding: 0.5em 1em;
+	background: #ffffff00 url('disclosure_down.png') top right no-repeat;
+}

doc/sources/.templates/layout.html

@@ -46,6 +46,8 @@
       {%- if not embedded %}{% if not theme_nosidebar|tobool %}
       <div class="sphinxsidebar">
         <div class="sphinxsidebarwrapper">
+            <h3>Version</h3>
+            <select id="version_selector"></select>
             <h3>Quick search</h3>
             <form class="search" action="{{ pathto('search') }}" method="get">
                 &nbsp;
@@ -101,6 +103,7 @@
         COLLAPSE_MODINDEX: false,
         FILE_SUFFIX: '{{ file_suffix }}',
         HAS_SOURCE:  {{ has_source|lower }}
+
       };
     </script>
     {%- for scriptfile in script_files %}
@@ -226,6 +229,30 @@
     g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'pw.js'; s.parentNode.insertBefore(g,s);
   })();
 </script>
+<script>
+  var selector = $("#version_selector");
+
+  selector.on('change', function() {
+    var current = document.location.pathname;
+    // TODO find a better way to replace the current version with the new one
+    var target = current.split('/');
+    target.shift();
+    var prefix = target.shift();
+    target.shift();
+    document.location.pathname = ["", prefix, this.value].concat(target).join('/');
+  });
+
+  var url = "{{ url_root }}/versions.json";
+
+  $.getJSON(url, function(versions) {
+    versions.forEach(function(version){
+      var current = window.location.pathname.split('/')[2]
+      selector.append(
+        $("<option " + (version == current ? "selected" : "") + "/>").val(version).html(version)
+      );
+    });
+  });
+</script>
 <noscript><p><img src="//pw.kivy.org/pw.php?idsite=4&rec=1" style="border:0;" alt="" /></p></noscript>
 <!-- End Piwik Tracking Code -->
     <!--