adjust docs for versioning

Makefile

@@ -18,3 +18,6 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# To make the version_management module visible while building the documentation
+export PYTHONPATH := $(SOURCEDIR):$(PYTHONPATH)

_static/css/furo-phoenix.css

@@ -148,13 +148,104 @@ img {
     border-right: none !important;
     box-sizing: border-box;
     display: flex;
-    justify-content: flex-start !important;
-    width: 17em !important
+    justify-content: flex-end;
+    flex-direction: column !important;
+    height: 100vh !important;
+    width: 17em !important;
+    position: fixed !important
 }
 
 .sidebar-container {
     box-sizing: border-box;
-    width: 17em !important
+    width: inherit !important;
+    overflow-y: auto !important;
+    flex-grow: 1 !important
+}
+
+.sidebar-sticky {
+    height: 100% !important;
+    overflow-y: hidden !important
+}
+
+.version-container {
+    width: inherit !important;
+    border-top: 1px solid #c2cbcb !important;
+    background-color: #f1f3f3 !important;
+    font-family: 'Open Sans', sans-serif !important;
+    font-weight: 600 !important;
+    color: var(--color-sidebar-link-text--top-level) !important
+}
+
+.default-version {
+    display: flex !important;
+    justify-content: space-between !important;
+    cursor: pointer !important
+}
+
+.default-version:hover {
+    background-color: #ea5b22 !important;
+    color: white !important
+}
+
+.default-version > label {
+    display: flex !important;
+    align-items: center !important;
+    justify-content: center !important;
+    cursor: pointer !important;
+    width: var(--sidebar-expander-width) !important;
+    height: var(--sidebar-item-height) !important
+}
+
+.version-top {
+    flex: 1 !important;
+    display: flex !important;
+    justify-content: space-between !important;
+    align-items: center !important;
+    padding-left: 10px !important
+}
+
+.version-container.shift-up > .default-version label > .icon > svg {
+    transform: rotate(-90deg) !important
+}
+
+.default-version label > .icon > svg {
+    transform: rotate(90deg) !important
+}
+
+.version-container.shift-up .other-versions {
+    display: block !important
+}
+
+.other-versions {
+    margin-right: 10px !important;
+    margin-left: 10px !important;
+    box-sizing: border-box !important;
+    display: none !important
+}
+
+.other-versions > dl {
+    margin-top: 7px !important
+}
+
+.other-versions > dl > dd {
+    display: inline-block !important;
+    margin: 0 !important;
+    padding: 5px !important
+}
+
+.other-versions > dl > dd > a {
+    text-decoration: none !important;
+    font-weight: 500 !important;
+    color: var(--color-sidebar-link-text--top-level) !important
+}
+
+.other-versions > dl > dd > a:hover {
+    font-weight: 500 !important;
+    color: #ea5b22 !important
+}
+
+.main {
+    margin-left: 17em !important
 }
 
 /* Hide sidebar brand text */

_static/js/functions.js

@@ -5,25 +5,33 @@ function findRelativePath()
 
 	if (window.location.origin === 'null') {
 		// Local run
-		let fullPath = window.location.href;
-		let index = fullPath.indexOf('_build/html');
+		const fullPath = window.location.href;
+		const index = fullPath.indexOf('_build/html');
 		currentPath = fullPath.substring(index);
 		path = '_build/html/libc/functions/index.html';
 	}
 	else {
 		// Server run
-		currentPath = window.location.href;
-		path = window.location.origin + '/libc/functions/index.html';
+		currentPath = window.location.pathname;
+		const pathSegments = currentPath.split('/').filter(segment => segment !== '');
+		const firstItem = pathSegments[0] || null;
+
+		if (firstItem === 'latest' || /^[0-9]+\.[0-9]+\.[0-9]+$/.test(firstItem)) {
+			path = firstItem + '/libc/functions/index.html';
+		}
+		else {
+			path = '/libc/functions/index.html';
+		}
 	}
 
-	let fromSegments = currentPath.split('/');
-	let toSegments = path.split('/');
+	const fromSegments = currentPath.split('/');
+	const toSegments = path.split('/');
 
 	if (fromSegments.join() === toSegments.join()) {
 		if (window.location.origin === 'null') {
 			// Local run
-			let fullPath = window.location.href;
-			let index = fullPath.indexOf('_build/html');
+			const fullPath = window.location.href;
+			const index = fullPath.indexOf('_build/html');
 
 			return fullPath.substring(0, index) + path;
 		}
@@ -50,11 +58,11 @@ function findRelativePath()
 
 function getElementsByTagNameWithDepth(element, tagName, depthLimit, currentDepth = 0)
 {
-	var elements = [];
-	var children = element.children;
+	let elements = [];
+	const children = element.children;
 
 	for (let i = 0; i < children.length; i++) {
-		let child = children[i];
+		const child = children[i];
 		if (child.tagName.toLowerCase() === tagName.toLowerCase()) {
 			elements.push(child);
 		}
@@ -126,13 +134,13 @@ headersLi.forEach(function(list) {
 		}
 	});
 
-	let anchor = list.querySelector('a');
+	const anchor = list.querySelector('a');
 	// Slashes and dots in headers are replaced with '-'
-	let textContent = anchor.textContent
+	const textContent = anchor.textContent
 		.replace(/\//g, '-')
 		.replace(/\.h/g, '-h');
 
-	let relativePath = findRelativePath() + '#' + textContent;
+	const relativePath = findRelativePath() + '#' + textContent;
 
 	anchor.setAttribute('href', relativePath);
 

_static/js/versions.js

@@ -0,0 +1,30 @@
+const curr_version = document.querySelector('.curr-version');
+const currentPath = window.location.pathname;
+const pathSegments = currentPath.split('/').filter(segment => segment !== '');
+const firstItem = pathSegments[0] || null;
+
+if (firstItem !== null &&
+   (/^[0-9]+\.[0-9]+\.[0-9]+$/.test(firstItem)))
+{
+    curr_version.textContent = 'ver. ' + firstItem;
+}
+// version directories not available - marking the current version as latest
+else {
+    curr_version.textContent = 'ver. latest';
+}
+
+const versions = document.querySelector('.other-versions');
+
+versions.querySelectorAll('a').forEach(anchor => {
+    anchor.addEventListener('click', function() {
+        baseTag.href = window.location.origin + anchor.textContent + '/';
+    });
+});
+
+const triggerElement = document.querySelector('.default-version');
+const versionContainer = document.querySelector('.version-container');
+const sidebarContainer = document.querySelector('.sidebar-container');
+
+triggerElement.addEventListener('click', function() {
+    versionContainer.classList.toggle('shift-up');
+});

_templates/page.html

@@ -57,6 +57,7 @@
       </div>
       {% endblock left_sidebar %}
     </div>
+    {% include "versions.html" %}
   </aside>
   <div class="main">
     <div class="content">

_templates/versions.html

@@ -0,0 +1,19 @@
+<div class="version-container">
+    <div class="default-version">
+        <span class="version-top">
+            <span>Phoenix-RTOS</span>
+            <span class="curr-version">ver. latest</span>
+        </span>
+        <label>
+            <i class="icon"><svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg></i>
+        </label>
+    </div>
+    <div class="other-versions">
+        <dl>
+            <span>Document Release Versions:</span>
+            {% for name, url in versions %}
+                <dd><a href="{{ url }}">{{ name }}</a></dd>
+            {% endfor %}
+        </dl>
+    </div>
+</div>

conf.py

@@ -6,73 +6,75 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = ''
-copyright = '2024, Phoenix Systems'
-author = 'Phoenix Systems'
+from version_management import get_version_context
+
+
+project = ""
+copyright = "2024, Phoenix Systems"
+author = "Phoenix Systems"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = [
-    'myst_parser',
-    'sphinx_copybutton'
-]
+extensions = ["myst_parser", "sphinx_copybutton"]
 
-templates_path = ['_templates']
-exclude_patterns = ['README.md', '_build', 'Thumbs.db', '.DS_Store']
+templates_path = ["_templates"]
+exclude_patterns = ["README.md", "_build", "Thumbs.db", ".DS_Store"]
 myst_heading_anchors = 3
-pygments_dark_style = 'tango'
+pygments_dark_style = "tango"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_title = 'Phoenix-RTOS Documentation'
-html_favicon = '_images/RTOS_sign.png'
-html_theme = 'furo'
-html_js_files = ['js/functions.js']
-html_style = ['css/furo-phoenix.css', 'css/furo-extensions-phoenix.css']
-html_static_path = ['_static', '_images']
+html_title = "Phoenix-RTOS Documentation"
+html_favicon = "_images/RTOS_sign.png"
+html_theme = "furo"
+html_js_files = ["js/functions.js", "js/versions.js"]
+html_style = ["css/furo-phoenix.css", "css/furo-extensions-phoenix.css"]
+html_static_path = ["_static", "_images"]
+html_baseurl = "https://docs.phoenix-rtos.com/latest/"
+html_context = {"versions": get_version_context()}
+
 # TODO: add dark mode support
 html_theme_options = {
-	"light_logo": "light_logo.png",
-	"light_css_variables": {
-		"sidebar-caption-font-size": "100%",
-		"sidebar-item-font-size": "90%",
-		"sidebar-item-spacing-vertical": "0.4rem",
-		"sidebar-item-line-height": "1.1rem",
-		"color-sidebar-search-icon": "#EA5B22",
-		"sidebar-search-space-above": "0.1rem",
-		"sidebar-caption-space-above": "0.1rem",
-		"sidebar-tree-space-above": "0.5rem",
-		"sidebar-search-input-font-size": "95%",
-		"font-stack": "'Open Sans', sans-serif",
-		"color-sidebar-background": "#0F1724",
-		"color-sidebar-link-text--top-level": "#273149",
-		"color-sidebar-item-background--current": "F1F3F3",
-		"color-foreground-primary": "#273149",
-		"color-brand-content": "#1890d7",
-		"color-header-background": "#0F1724",
-		"color-header-text": "white"
-	},
-
-	"dark_logo": "light_logo.png",
-	"dark_css_variables": {
-		"sidebar-caption-font-size": "100%",
-		"sidebar-item-font-size": "90%",
-		"sidebar-item-spacing-vertical": "0.4rem",
-		"sidebar-item-line-height": "1.1rem",
-		"color-sidebar-search-icon": "#EA5B22",
-		"sidebar-search-space-above": "0.1rem",
-		"sidebar-caption-space-above": "0.1rem",
-		"sidebar-tree-space-above": "0.5rem",
-		"sidebar-search-input-font-size": "95%",
-		"font-stack": "'Open Sans', sans-serif",
-		"color-sidebar-background": "#0F1724",
-		"color-sidebar-link-text--top-level": "#273149",
-		"color-sidebar-item-background--current": "#0F1F3F3",
-		"color-foreground-primary": "#273149",
-		"color-brand-content": "#1890d7",
-		"color-header-background": "#0F1724",
-		"color-header-text": "white"
-	}
+    "light_logo": "light_logo.png",
+    "light_css_variables": {
+        "sidebar-caption-font-size": "100%",
+        "sidebar-item-font-size": "90%",
+        "sidebar-item-spacing-vertical": "0.4rem",
+        "sidebar-item-line-height": "1.1rem",
+        "color-sidebar-search-icon": "#EA5B22",
+        "sidebar-search-space-above": "0.1rem",
+        "sidebar-caption-space-above": "0.1rem",
+        "sidebar-tree-space-above": "0.5rem",
+        "sidebar-search-input-font-size": "95%",
+        "font-stack": "'Open Sans', sans-serif",
+        "color-sidebar-background": "#0F1724",
+        "color-sidebar-link-text--top-level": "#273149",
+        "color-sidebar-item-background--current": "F1F3F3",
+        "color-foreground-primary": "#273149",
+        "color-brand-content": "#1890d7",
+        "color-header-background": "#0F1724",
+        "color-header-text": "white",
+    },
+    "dark_logo": "light_logo.png",
+    "dark_css_variables": {
+        "sidebar-caption-font-size": "100%",
+        "sidebar-item-font-size": "90%",
+        "sidebar-item-spacing-vertical": "0.4rem",
+        "sidebar-item-line-height": "1.1rem",
+        "color-sidebar-search-icon": "#EA5B22",
+        "sidebar-search-space-above": "0.1rem",
+        "sidebar-caption-space-above": "0.1rem",
+        "sidebar-tree-space-above": "0.5rem",
+        "sidebar-search-input-font-size": "95%",
+        "font-stack": "'Open Sans', sans-serif",
+        "color-sidebar-background": "#0F1724",
+        "color-sidebar-link-text--top-level": "#273149",
+        "color-sidebar-item-background--current": "#0F1F3F3",
+        "color-foreground-primary": "#273149",
+        "color-brand-content": "#1890d7",
+        "color-header-background": "#0F1724",
+        "color-header-text": "white",
+    },
 }