From ad2e3e614696e098cb4ab1791cb402adaa16d033 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Mon, 7 Sep 2020 12:44:48 +0200 Subject: sphinx: Add support for multiple docs version Enhance the sphinx experience/nagivation with: * Remove the pointless looking parts of breadcrumb navigtation * Add a document type switcher to the breadcrumb navigation * Add a version selection switch to the breadcrumb navigation (From yocto-docs rev: 1823624bdb9ea002d44c9e6d0fd4cd662bff36ad) Signed-off-by: Richard Purdie --- documentation/_templates/breadcrumbs.html | 14 ++ documentation/_templates/layout.html | 9 ++ documentation/conf.py | 18 ++- documentation/index.rst | 2 +- documentation/sphinx-static/switchers.js | 233 ++++++++++++++++++++++++++++++ 5 files changed, 270 insertions(+), 6 deletions(-) create mode 100644 documentation/_templates/breadcrumbs.html create mode 100644 documentation/_templates/layout.html create mode 100644 documentation/sphinx-static/switchers.js (limited to 'documentation') diff --git a/documentation/_templates/breadcrumbs.html b/documentation/_templates/breadcrumbs.html new file mode 100644 index 0000000000..eb6244b74c --- /dev/null +++ b/documentation/_templates/breadcrumbs.html @@ -0,0 +1,14 @@ +{% extends "!breadcrumbs.html" %} + +{% block breadcrumbs %} +
  • + {{ doctype or 'single' }} + {{ release }} +
    • +
  • »
    • + {% for doc in parents %} +
  • {{ doc.title }} »
    • + {% endfor %} +
  • {{ title }}
    • +{% endblock %} + diff --git a/documentation/_templates/layout.html b/documentation/_templates/layout.html new file mode 100644 index 0000000000..af4c6acc60 --- /dev/null +++ b/documentation/_templates/layout.html @@ -0,0 +1,9 @@ +{% extends "!layout.html" %} + +{% set script_files = script_files + ['_static/switchers.js'] %} + +{% block extrabody %} +
    +
    +{% endblock %} + diff --git a/documentation/conf.py b/documentation/conf.py index 546ca723a9..66af9fa060 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -12,18 +12,25 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - +import os +import sys import datetime +current_version = "dev" + +# String used in sidebar +version = 'Version: ' + current_version +if current_version == 'dev': + version = 'Version: Current Development' +# Version seen in documentation_options.js and hence in js switchers code +release = current_version + + # -- Project information ----------------------------------------------------- project = 'The Yocto Project' copyright = '2010-%s, The Linux Foundation' % datetime.datetime.now().year author = 'The Linux Foundation' - # -- General configuration --------------------------------------------------- # to load local extension from the folder 'sphinx' @@ -96,4 +103,5 @@ html_context = { 'css_files': [ '_static/theme_overrides.css', ], + 'current_version': current_version, } diff --git a/documentation/index.rst b/documentation/index.rst index 151589addc..4e8b3647f4 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -40,7 +40,7 @@ Welcome to The Yocto Project's documentation! :maxdepth: 1 :caption: 'Mega' Manual - All-in-one 'Mega' Manual + All-in-one 'Mega' Manual .. toctree:: :maxdepth: 1 diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js new file mode 100644 index 0000000000..c8a94d93ba --- /dev/null +++ b/documentation/sphinx-static/switchers.js @@ -0,0 +1,233 @@ +(function() { + 'use strict'; + + var all_versions = { + 'dev': 'dev (3.2)', + '3.1.2': '3.1.2', + '3.0.3': '3.0.3', + '2.7.4': '2.7.4', + }; + + var all_doctypes = { + 'single': 'Individual Webpages', + 'mega': "All-in-one 'Mega' Manual", + }; + + // Simple version comparision + // Return 1 if a > b + // Return -1 if a < b + // Return 0 if a == b + function ver_compare(a, b) { + if (a == "dev") { + return 1; + } + + if (a === b) { + return 0; + } + + var a_components = a.split("."); + var b_components = b.split("."); + + var len = Math.min(a_components.length, b_components.length); + + // loop while the components are equal + for (var i = 0; i < len; i++) { + // A bigger than B + if (parseInt(a_components[i]) > parseInt(b_components[i])) { + return 1; + } + + // B bigger than A + if (parseInt(a_components[i]) < parseInt(b_components[i])) { + return -1; + } + } + + // If one's a prefix of the other, the longer one is greater. + if (a_components.length > b_components.length) { + return 1; + } + + if (a_components.length < b_components.length) { + return -1; + } + + // Otherwise they are the same. + return 0; + } + + function build_version_select(current_series, current_version) { + var buf = [''); + return buf.join(''); + } + + function build_doctype_select(current_doctype) { + var buf = [''); + return buf.join(''); + } + + function navigate_to_first_existing(urls) { + // Navigate to the first existing URL in urls. + var url = urls.shift(); + + // Web browsers won't redirect file:// urls to file urls using ajax but + // its useful for local testing + if (url.startsWith("file://")) { + window.location.href = url; + return; + } + + if (urls.length == 0) { + window.location.href = url; + return; + } + $.ajax({ + url: url, + success: function() { + window.location.href = url; + }, + error: function() { + navigate_to_first_existing(urls); + } + }); + } + + function get_docroot_url() { + var url = window.location.href; + var root = DOCUMENTATION_OPTIONS.URL_ROOT; + + var urlarray = url.split('/'); + // Trim off anything after '/' + urlarray.pop(); + var depth = (root.match(/\.\.\//g) || []).length; + for (var i = 0; i < depth; i++) { + urlarray.pop(); + } + + return urlarray.join('/') + '/'; + } + + function on_version_switch() { + var selected_version = $(this).children('option:selected').attr('value'); + var url = window.location.href; + var current_version = DOCUMENTATION_OPTIONS.VERSION; + var docroot = get_docroot_url() + + var new_versionpath = selected_version + '/'; + if (selected_version == "dev") + new_versionpath = ''; + + // dev versions have no version prefix + if (current_version == "dev") { + var new_url = docroot + new_versionpath + url.replace(docroot, ""); + var fallback_url = docroot + new_versionpath; + } else { + var new_url = url.replace('/' + current_version + '/', '/' + new_versionpath); + var fallback_url = new_url.replace(url.replace(docroot, ""), ""); + } + + console.log(get_docroot_url()) + console.log(url + " to url " + new_url); + console.log(url + " to fallback " + fallback_url); + + if (new_url != url) { + navigate_to_first_existing([ + new_url, + fallback_url, + 'https://www.yoctoproject.org/docs/', + ]); + } + } + + function on_doctype_switch() { + var selected_doctype = $(this).children('option:selected').attr('value'); + var url = window.location.href; + if (selected_doctype == 'mega') { + var docroot = get_docroot_url() + var current_version = DOCUMENTATION_OPTIONS.VERSION; + // Assume manuals before 3.2 are using old docbook mega-manual + if (ver_compare(current_version, "3.2") < 0) { + var new_url = docroot + "/mega-manual/mega-manual.html"; + } else { + var new_url = docroot + "/singleindex.html"; + } + } else { + var new_url = url.replace("/singleindex.html", "/index.html") + } + + if (new_url != url) { + navigate_to_first_existing([ + new_url, + 'https://www.yoctoproject.org/docs/', + ]); + } + } + + // Returns the current doctype based upon the url + function doctype_segment_from_url(url) { + if (url.includes("singleindex") || url.includes("mega-manual")) + return "mega"; + return "single"; + } + + $(document).ready(function() { + var release = DOCUMENTATION_OPTIONS.VERSION; + var current_doctype = doctype_segment_from_url(window.location.href); + var current_series = release.substr(0, 3); + var version_select = build_version_select(current_series, release); + + $('.version_switcher_placeholder').html(version_select); + $('.version_switcher_placeholder select').bind('change', on_version_switch); + + var doctype_select = build_doctype_select(current_doctype); + + $('.doctype_switcher_placeholder').html(doctype_select); + $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch); + + if (ver_compare(release, "3.1") < 0) { + $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version'); + $('#outdated-warning').css('padding', '.5em'); + } else if (release != "dev") { + $.each(all_versions, function(version, title) { + var series = version.substr(0, 3); + if (series == current_series && version != release) { + $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, ' + version + '.'); + $('#outdated-warning').css('padding', '.5em'); + } + }); + } + }); +})(); -- cgit v1.2.3-54-g00ecf