From 4b97afa6760298504cca34adbe71417368ed834b Mon Sep 17 00:00:00 2001 From: Gabriel Pettier Date: Sat, 7 Jul 2018 02:12:20 +0200 Subject: [PATCH] Maintain separate docs for different releases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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//…. - theming could certainly be slightly improved. --- .travis.yml | 17 ++++++++++++----- doc/sources/.static/fresh.css | 9 +++++++++ doc/sources/.templates/layout.html | 27 +++++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 5 deletions(-) diff --git a/.travis.yml b/.travis.yml index a039f0db7..ce1237b77 100644 --- a/.travis.yml +++ b/.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: diff --git a/doc/sources/.static/fresh.css b/doc/sources/.static/fresh.css index 4c5fdfb59..220c1a758 100644 --- a/doc/sources/.static/fresh.css +++ b/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; +} diff --git a/doc/sources/.templates/layout.html b/doc/sources/.templates/layout.html index 85e7f7bc1..8a641cf90 100644 --- a/doc/sources/.templates/layout.html +++ b/doc/sources/.templates/layout.html @@ -46,6 +46,8 @@ {%- if not embedded %}{% if not theme_nosidebar|tobool %}
+

Version

+

Quick search

  @@ -101,6 +103,7 @@ COLLAPSE_MODINDEX: false, FILE_SUFFIX: '{{ file_suffix }}', HAS_SOURCE: {{ has_source|lower }} + }; {%- 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); })(); +