summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-08 16:29:59 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-16 18:14:08 +0100
commitcaf24e8ddd7105cbb04c026fbb90c19981c62d50 (patch)
tree061402a498b49e3f798797e0ecc1163a4a217ddc /bitbake/doc
parent390fc75bd6705ee55ec9f35f09bfa715f81024e2 (diff)
downloadpoky-caf24e8ddd7105cbb04c026fbb90c19981c62d50.tar.gz
bitbake: sphinx: 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 (Bitbake rev: cb19159cf8972713a2063387849804c5cea72d24) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org> Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/_templates/breadcrumbs.html14
-rw-r--r--bitbake/doc/_templates/layout.html7
-rw-r--r--bitbake/doc/conf.py10
-rw-r--r--bitbake/doc/sphinx-static/switchers.js233
4 files changed, 264 insertions, 0 deletions
diff --git a/bitbake/doc/_templates/breadcrumbs.html b/bitbake/doc/_templates/breadcrumbs.html
new file mode 100644
index 0000000000..eb6244b74c
--- /dev/null
+++ b/bitbake/doc/_templates/breadcrumbs.html
@@ -0,0 +1,14 @@
1{% extends "!breadcrumbs.html" %}
2
3{% block breadcrumbs %}
4 <li>
5 <span class="doctype_switcher_placeholder">{{ doctype or 'single' }}</span>
6 <span class="version_switcher_placeholder">{{ release }}</span>
7 </li>
8 <li> &raquo;</li>
9 {% for doc in parents %}
10 <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
11 {% endfor %}
12 <li>{{ title }}</li>
13{% endblock %}
14
diff --git a/bitbake/doc/_templates/layout.html b/bitbake/doc/_templates/layout.html
new file mode 100644
index 0000000000..308d5c7a28
--- /dev/null
+++ b/bitbake/doc/_templates/layout.html
@@ -0,0 +1,7 @@
1{% extends "!layout.html" %}
2
3{% block extrabody %}
4<div id="outdated-warning" style="text-align: center; background-color: #FFBABA; color: #6A0E0E;">
5</div>
6{% endblock %}
7
diff --git a/bitbake/doc/conf.py b/bitbake/doc/conf.py
index 4ff90e8dbf..722c79230b 100644
--- a/bitbake/doc/conf.py
+++ b/bitbake/doc/conf.py
@@ -16,6 +16,15 @@
16 16
17import datetime 17import datetime
18 18
19current_version = "dev"
20
21# String used in sidebar
22version = 'Version: ' + current_version
23if current_version == 'dev':
24 version = 'Version: Current Development'
25# Version seen in documentation_options.js and hence in js switchers code
26release = current_version
27
19# -- Project information ----------------------------------------------------- 28# -- Project information -----------------------------------------------------
20 29
21project = 'Bitbake' 30project = 'Bitbake'
@@ -67,6 +76,7 @@ html_static_path = ['sphinx-static']
67 76
68# Add customm CSS and JS files 77# Add customm CSS and JS files
69html_css_files = ['theme_overrides.css'] 78html_css_files = ['theme_overrides.css']
79html_js_files = ['switchers.js']
70 80
71# Hide 'Created using Sphinx' text 81# Hide 'Created using Sphinx' text
72html_show_sphinx = False 82html_show_sphinx = False
diff --git a/bitbake/doc/sphinx-static/switchers.js b/bitbake/doc/sphinx-static/switchers.js
new file mode 100644
index 0000000000..c8a94d93ba
--- /dev/null
+++ b/bitbake/doc/sphinx-static/switchers.js
@@ -0,0 +1,233 @@
1(function() {
2 'use strict';
3
4 var all_versions = {
5 'dev': 'dev (3.2)',
6 '3.1.2': '3.1.2',
7 '3.0.3': '3.0.3',
8 '2.7.4': '2.7.4',
9 };
10
11 var all_doctypes = {
12 'single': 'Individual Webpages',
13 'mega': "All-in-one 'Mega' Manual",
14 };
15
16 // Simple version comparision
17 // Return 1 if a > b
18 // Return -1 if a < b
19 // Return 0 if a == b
20 function ver_compare(a, b) {
21 if (a == "dev") {
22 return 1;
23 }
24
25 if (a === b) {
26 return 0;
27 }
28
29 var a_components = a.split(".");
30 var b_components = b.split(".");
31
32 var len = Math.min(a_components.length, b_components.length);
33
34 // loop while the components are equal
35 for (var i = 0; i < len; i++) {
36 // A bigger than B
37 if (parseInt(a_components[i]) > parseInt(b_components[i])) {
38 return 1;
39 }
40
41 // B bigger than A
42 if (parseInt(a_components[i]) < parseInt(b_components[i])) {
43 return -1;
44 }
45 }
46
47 // If one's a prefix of the other, the longer one is greater.
48 if (a_components.length > b_components.length) {
49 return 1;
50 }
51
52 if (a_components.length < b_components.length) {
53 return -1;
54 }
55
56 // Otherwise they are the same.
57 return 0;
58 }
59
60 function build_version_select(current_series, current_version) {
61 var buf = ['<select>'];
62
63 $.each(all_versions, function(version, title) {
64 var series = version.substr(0, 3);
65 if (series == current_series) {
66 if (version == current_version)
67 buf.push('<option value="' + version + '" selected="selected">' + title + '</option>');
68 else
69 buf.push('<option value="' + version + '">' + title + '</option>');
70
71 if (version != current_version)
72 buf.push('<option value="' + current_version + '" selected="selected">' + current_version + '</option>');
73 } else {
74 buf.push('<option value="' + version + '">' + title + '</option>');
75 }
76 });
77
78 buf.push('</select>');
79 return buf.join('');
80 }
81
82 function build_doctype_select(current_doctype) {
83 var buf = ['<select>'];
84
85 $.each(all_doctypes, function(doctype, title) {
86 if (doctype == current_doctype)
87 buf.push('<option value="' + doctype + '" selected="selected">' +
88 all_doctypes[current_doctype] + '</option>');
89 else
90 buf.push('<option value="' + doctype + '">' + title + '</option>');
91 });
92 if (!(current_doctype in all_doctypes)) {
93 // In case we're browsing a doctype that is not yet in all_doctypes.
94 buf.push('<option value="' + current_doctype + '" selected="selected">' +
95 current_doctype + '</option>');
96 all_doctypes[current_doctype] = current_doctype;
97 }
98 buf.push('</select>');
99 return buf.join('');
100 }
101
102 function navigate_to_first_existing(urls) {
103 // Navigate to the first existing URL in urls.
104 var url = urls.shift();
105
106 // Web browsers won't redirect file:// urls to file urls using ajax but
107 // its useful for local testing
108 if (url.startsWith("file://")) {
109 window.location.href = url;
110 return;
111 }
112
113 if (urls.length == 0) {
114 window.location.href = url;
115 return;
116 }
117 $.ajax({
118 url: url,
119 success: function() {
120 window.location.href = url;
121 },
122 error: function() {
123 navigate_to_first_existing(urls);
124 }
125 });
126 }
127
128 function get_docroot_url() {
129 var url = window.location.href;
130 var root = DOCUMENTATION_OPTIONS.URL_ROOT;
131
132 var urlarray = url.split('/');
133 // Trim off anything after '/'
134 urlarray.pop();
135 var depth = (root.match(/\.\.\//g) || []).length;
136 for (var i = 0; i < depth; i++) {
137 urlarray.pop();
138 }
139
140 return urlarray.join('/') + '/';
141 }
142
143 function on_version_switch() {
144 var selected_version = $(this).children('option:selected').attr('value');
145 var url = window.location.href;
146 var current_version = DOCUMENTATION_OPTIONS.VERSION;
147 var docroot = get_docroot_url()
148
149 var new_versionpath = selected_version + '/';
150 if (selected_version == "dev")
151 new_versionpath = '';
152
153 // dev versions have no version prefix
154 if (current_version == "dev") {
155 var new_url = docroot + new_versionpath + url.replace(docroot, "");
156 var fallback_url = docroot + new_versionpath;
157 } else {
158 var new_url = url.replace('/' + current_version + '/', '/' + new_versionpath);
159 var fallback_url = new_url.replace(url.replace(docroot, ""), "");
160 }
161
162 console.log(get_docroot_url())
163 console.log(url + " to url " + new_url);
164 console.log(url + " to fallback " + fallback_url);
165
166 if (new_url != url) {
167 navigate_to_first_existing([
168 new_url,
169 fallback_url,
170 'https://www.yoctoproject.org/docs/',
171 ]);
172 }
173 }
174
175 function on_doctype_switch() {
176 var selected_doctype = $(this).children('option:selected').attr('value');
177 var url = window.location.href;
178 if (selected_doctype == 'mega') {
179 var docroot = get_docroot_url()
180 var current_version = DOCUMENTATION_OPTIONS.VERSION;
181 // Assume manuals before 3.2 are using old docbook mega-manual
182 if (ver_compare(current_version, "3.2") < 0) {
183 var new_url = docroot + "/mega-manual/mega-manual.html";
184 } else {
185 var new_url = docroot + "/singleindex.html";
186 }
187 } else {
188 var new_url = url.replace("/singleindex.html", "/index.html")
189 }
190
191 if (new_url != url) {
192 navigate_to_first_existing([
193 new_url,
194 'https://www.yoctoproject.org/docs/',
195 ]);
196 }
197 }
198
199 // Returns the current doctype based upon the url
200 function doctype_segment_from_url(url) {
201 if (url.includes("singleindex") || url.includes("mega-manual"))
202 return "mega";
203 return "single";
204 }
205
206 $(document).ready(function() {
207 var release = DOCUMENTATION_OPTIONS.VERSION;
208 var current_doctype = doctype_segment_from_url(window.location.href);
209 var current_series = release.substr(0, 3);
210 var version_select = build_version_select(current_series, release);
211
212 $('.version_switcher_placeholder').html(version_select);
213 $('.version_switcher_placeholder select').bind('change', on_version_switch);
214
215 var doctype_select = build_doctype_select(current_doctype);
216
217 $('.doctype_switcher_placeholder').html(doctype_select);
218 $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch);
219
220 if (ver_compare(release, "3.1") < 0) {
221 $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version');
222 $('#outdated-warning').css('padding', '.5em');
223 } else if (release != "dev") {
224 $.each(all_versions, function(version, title) {
225 var series = version.substr(0, 3);
226 if (series == current_series && version != release) {
227 $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, ' + version + '.');
228 $('#outdated-warning').css('padding', '.5em');
229 }
230 });
231 }
232 });
233})();