Mirrors_UI_SDK/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2026-05-26 11:07:34 +08:00
Code Issues Actions 23 Packages Projects Releases Wiki Activity

docs(furo): convert to furo theme...

Browse Source 
requirements.txt, conf.py and page.html template:
-------------------------------------------------
- Remove `sphinx_rtd_theme` items.
- Add `furo` theme items.
- Remove `layout.html` template -- `furo` theme doesn't use it.

Top index.rst:
--------------
- Remove hidden TOC (not compatible with `furo` theme).
- Add back in message at end of build.py that 2 warnings are expected
  about 2 `.rst` files not being in any TOC.

Replacing things `sphinx_rtd_theme` did automatically:
------------------------------------------------------
- Include FontAwesome-related font and .css files needed by some of our styles.
- Include jQuery.js previously used by `sphinx_rtd_theme`.

For Documentation Version Selector:
-----------------------------------
- Selector and insertion method needed to be fixed to work with the
  Furo HTML element structure in the upper part of the nav sidebar.
- Moved styling from `page.html` template to `custom.css`.
- Fix dropdown coloring so it switches with (light/dark) theme.
- Document JavaScript added by `page.html` template.
This commit is contained in:
Victor Wheeler
2025-04-22 11:07:21 -06:00
committed by Gabor Kiss-Vamosi
parent c033a98afd
commit 2129d37bca
12 changed files with 182 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/build.py
+1
View File
@@ -747,6 +747,7 @@ def run(args):
# ---------------------------------------------------------------------
t_end = datetime.now()
announce(__file__, 'Total run time: ' + str(t_end - t0))
announce(__file__, '\n\nNote: warnings about `details/index.rst` and `intro/index.rst` not being in any toctree are expected and okay.\n')
announce(__file__, 'Done.')
docs/requirements.txt
+3 -2
View File
@@ -2,7 +2,6 @@ Sphinx
breathe
imagesize
importlib-metadata
sphinx-rtd-theme
sphinx-sitemap
sphinxcontrib-applehelp
sphinxcontrib-devhelp
@@ -11,8 +10,10 @@ sphinxcontrib-jsmath
sphinxcontrib-qthelp
sphinxcontrib-serializinghtml
sphinxcontrib-mermaid==0.9.2
sphinx-copybutton
sphinx-design
sphinx-rtd-dark-mode
typing-extensions
sphinx-reredirects
dirsync
furo
accessible-pygments
docs/src/_static/css/brands.min.css
Vendored
+6
View File
File diff suppressed because one or more lines are too long
docs/src/_static/css/custom.css
+35 -38
View File
@@ -1,3 +1,23 @@
/*-------------------------------------------------------------------------
* Connect FontAwesome file with FontAwesome family name. Supplements
* fontawesome.min.css. Without this, the codes like `fa-github` don't
# work in the Furo theme as they did with RTD theme.
*-------------------------------------------------------------------------*/
@font-face {
font-family: FontAwesome;
src:
url("../fonts/fontawesome-webfont.woff2") format("woff2"),
url("../fonts/fontawesome-webfont.woff") format("woff"),
}
.fa {
font-family: FontAwesome, "Lato", "proxima-nova", "Helvetica Neue", Arial, sans-serif;
cursor: pointer;
}
/*-------------------------------------------------------------------------
* Routine Element Overrides
*-------------------------------------------------------------------------*/
table, th, td {
border: 1px solid #bbb;
padding: 10px;
@@ -35,36 +55,14 @@ code.sig-name {
}
/*-------------------------------------------------------------------------
* All `wy-...` and `rst-content` classes are classes from
* `sphinx_rtd_theme` `layout.html` template.
*-------------------------------------------------------------------------
* `wy-side-nav-search` class adorns the <div> element in the upper left
* corner of each page that contains:
* - the LVGL logo
* - documentation-version selector drop-down (matches LVGL release versions)
* - search TextBox
*/
.wy-side-nav-search {
background-color: #f5f5f5;
}
.wy-side-nav-search > div.version {
color: #333;
display: none; /*replaced by dropdown*/
}
/* `rst-content` class marks the <div> element that contains the whole
* visible part of the right panel where the page content is shown. */
/*Let `code` wrap*/
.rst-content code, .rst-content tt, code {
white-space: normal;
}
.wy-nav-content {
padding: 1.618em 3.236em;
height: 100%;
max-width: 1920px;
margin: auto
* Version Dropdown Styling
*-------------------------------------------------------------------------*/
#version_dropdown {
background-color: var(--color-sidebar-background);
color: var(--color-foreground-primary);
margin: 4px 0;
width: 150px;
border-radius: 5px;
}
/*-------------------------------------------------------------------------
@@ -199,14 +197,6 @@ code.sig-name {
color: white;
}
/*-------------------------------------------------------------------------
* This doesn't select anything at this writing (29-Mar-2025).
*-------------------------------------------------------------------------
*/
dl.cpp.unexpanded dd {
display: none;
}
/*-------------------------------------------------------------------------
* The `lv-api-...` classes do not select anything at this writing (29-Mar-2025).
*-------------------------------------------------------------------------
@@ -232,6 +222,13 @@ dl.cpp.unexpanded dd {
content: "\f0d7 \00a0";
}
/* This hides the <dd> elements that contain a code-element's documentation
* when it has class "unexpanded". "expanded" and "unexpanded" classes in the
* <dl> elements are added and managed dynamically via code in `custom.js`. */
dl.cpp.unexpanded dd {
display: none;
}
/* Selects all <div> elements with "body" class.
* There are no elements that this selects at this writing (29-Mar-2025). */
div.body {
docs/src/_static/css/solid.min.css
Vendored
+6
View File
@@ -0,0 +1,6 @@
/*!
* Font Awesome Free 6.0.0 by @fontawesome - https://fontawesome.com
* License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
* Copyright 2022 Fonticons, Inc.
*/
:host,:root{--fa-font-solid:normal 900 1em/1 "Font Awesome 6 Free"}@font-face{font-family:"Font Awesome 6 Free";font-style:normal;font-weight:900;font-display:block;src:url(../webfonts/fa-solid-900.woff2) format("woff2"),url(../webfonts/fa-solid-900.ttf) format("truetype")}.fa-solid,.fas{font-family:"Font Awesome 6 Free";font-weight:900}
docs/src/_static/fonts/fontawesome-webfont.woff
BIN
View File
Binary file not shown.
docs/src/_static/fonts/fontawesome-webfont.woff2
BIN
View File
Binary file not shown.
docs/src/_static/jquery.js
Vendored
+2
View File
File diff suppressed because one or more lines are too long
docs/src/_templates/layout.html
-31
View File
@@ -1,31 +0,0 @@
{% extends "!layout.html" %}
{%- block extrahead %}
{{ super() }}
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-78811084-3"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-78811084-3', { 'anonymize_ip': true });
</script>
{% endblock %}
{% block footer %}
{{ super() }}
<div class="footer">This page uses <a href="https://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script type="text/javascript">
(function() {
var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ?
'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga);
})();
</script>
</div>
{% endblock %}
docs/src/_templates/page.html
+83 -16
View File
@@ -1,56 +1,123 @@
{% extends "!page.html" %}
{# ------------------------------------------------------------------------
# Including jquery.js here is needed for the Furo theme. RTD theme included it automatically.
# Note: having 'sphinxcontrib.jquery' in `conf.py` extensions list isn't working for this reason:
# it is including jQuery via `<script src="_static/jquery.js?v=5d32c60e"></script>`
# at the VERY END of the HTML element, right before `</body>` and so the jQuery code in the
# page will not execute becuase the `$` jQuery object has not been created yet! This is
# despite including 'sphinxcontrib.jquery' in `conf.py` extensions list DOES include
# `jquery.js` at the top of the page in simpler projects! Until it is sorted out why
# this is happening, we're having to include jQuery.js manually in the below code,
# and make it possible by storing the same `jquery.js` file that Sphinx RTD theme used
# in the `./docs/src/_static/` directory.
#
# One big difference that might be relevant: sphinx_rtd_theme simple projects include
# `jquery.js` at the top of each HTML page. With Furo theme, it is including it at the end.
# This might be relevant.
#
# We have to use an absolute path here because this code will be atop every page and the relative
# path varies since there is currently a 5-deep directory structure among the HTML pages.
# A `<base>` URL could solve that. Getting it to use local (workstation) jsquery.js
# file could require some JavaScript emitting the correct `<base>` and `<script>` elements
# based on the beginning part of `document.location.href`.
# ------------------------------------------------------------------------
#}
{%- block extrahead -%}
{{ super() }}
<script type="text/javascript" src="https://docs.lvgl.io/master/_static/jquery.js"></script>
{% endblock %}
{% block footer %}
{# This "call" to super() here is needed because Furo theme has content in "block footer" which RTD
theme did not have. Without it, this "block footer" section wipes out Furo's parent versions. #}
{{ super() }}
<style>
.wy-side-nav-search > div[role="search"] {
color: black;
}
</style>
<script type="text/javascript">
<script type="text/javascript">
$(document).ready(function() {
$(".toggle > *").hide();
$(".toggle .header").show();
$(".toggle .header").click(function() {
$(this).parent().children().not(".header").toggle(400);
$(this).parent().children().not(".header").toggle(300);
$(this).parent().children(".header").toggleClass("open");
})
});
</script>
<script type="text/javascript">
{# -------------------------------------------------------------------------
# Called by 'DOMContentLoaded' event listener below; adds
# documentation-version dropdown list just above search form in
# upper part of left (nav) panel.
# ------------------------------------------------------------------------ #}
function add_version_selector()
{
return fetch("https://raw.githubusercontent.com/lvgl/docs_compiled/gh-pages/versionlist.txt")
.then(res => res.text())
.then(text => {
const versions = text.split("\n").filter(version => version.trim().length > 0);
let p = document.getElementById("rtd-search-form").parentElement;
p.innerHTML = `
<select name="versions" id="versions" onchange="ver_sel()" style="border-radius:5px; margin-bottom:15px">
${versions.map(version => {
let versionName = "";
if(version == "master") versionName = "master (latest)";
else versionName = "v" + ((version.indexOf(".") != -1) ? version : (version + " (latest minor)"));
return `<option value="${version}">${versionName}</option>`;
})}
</select>` + p.innerHTML;
const version_list = text.split("\n").filter(version => version.trim().length > 0);
/* Note: class "sidebar-search-container" is part of Furo theme. */
let srch_form = document.getElementsByClassName("sidebar-search-container")[0];
let parent_div = srch_form.parentElement;
let select_elem_text = `
<select name="version" id="version_dropdown" onchange="ver_sel()">
${version_list.map(version => {
let versionName = "";
if(version == "master") versionName = "master (latest)";
else versionName = "v" + ((version.indexOf(".") != -1) ? version : (version + " (latest minor)"));
return `<option value="${version}">${versionName}</option>`;
})}
</select>`;
let node_array = jQuery.parseHTML(select_elem_text);
/* 1st node is a 'text' node. 2nd node is the <select> node.
* Insert <select> (dropdown list) node above search form. */
parent_div.insertBefore(node_array[1], srch_form);
});
}
{# -------------------------------------------------------------------------
# Fires when user selects a documentation version from version dropdown.
# ------------------------------------------------------------------------- #}
function ver_sel()
{
var x = document.getElementById("versions").value;
window.location.href = window.location.protocol + "//" + window.location.host + "/" + x + "/";
var x = document.getElementById("version_dropdown").value;
var new_url = window.location.protocol + "//" + window.location.host + "/" + x + "/";
if (new_url.startsWith('http')) {
window.location.href = new_url;
}
}
{# -------------------------------------------------------------------------
# Once: add documentation-version dropdown list just above search form in
# upper part of left panel.
# ------------------------------------------------------------------------- #}
document.addEventListener('DOMContentLoaded', (event) => {
add_version_selector().then(() => {
var value = window.location.pathname.split('/')[1];
document.getElementById("versions").value = value;
document.getElementById("version_dropdown").value = value;
});
})
{# -------------------------------------------------------------------------
# This listener delays loading (slow-to-load) examples until they are
# actually in view in the browser's viewport.
#
# Once: for each "lv-example" class element, adds observer which watches
# for that element to come into view in the browser's viewport. When it
# does, `onIntersection()` function is fired, causing example to be loaded
# if it hasn't already, or removed when its intersectionRatio <= 0.
# ------------------------------------------------------------------------- #}
document.addEventListener('DOMContentLoaded', (event) => {
function onIntersection(entries) {
entries.forEach(entry => {
docs/src/conf.py
+41 -29
View File
@@ -1,3 +1,4 @@
# #########################################################################
# Configuration file for the Sphinx documentation builder.
# Created by sphinx-quickstart on Wed Jun 12 16:38:40 2019.
#
@@ -17,6 +18,7 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath() to make it absolute, as shown here.
# #########################################################################
import os
import sys
from sphinx.builders.html import StandaloneHTMLBuilder
@@ -29,6 +31,8 @@ sys.path.insert(0, os.path.abspath('./_ext'))
sys.path.insert(0, base_path)
from lvgl_version import lvgl_version #NoQA
cfg_lv_version_file = 'lv_version.h'
# *************************************************************************
@@ -36,13 +40,21 @@ from lvgl_version import lvgl_version #NoQA
# *************************************************************************
project = 'LVGL'
copyright = '2024-%Y, LVGL Kft'
copyright = '2021-%Y, LVGL Kft'
author = 'LVGL Community'
if __name__ == '__main__':
version_src_path = os.path.join(base_path, '../../lv_version.h')
else:
version_src_path = os.path.join(base_path, 'lv_version.h')
version = lvgl_version(version_src_path)
version_src_path = os.path.join(base_path, cfg_lv_version_file)
if os.path.isfile(version_src_path):
# We have lv_version.h. Use it.
version = lvgl_version(version_src_path)
else:
# We have to guess.
version = '9.3'
release = version
# Notes about `version` here:
# ---------------------------
@@ -74,15 +86,16 @@ release = version
# As of 6-Jan-2025, `link_roles` is being commented out because it is being
# replaced by a manually-installed translation link in ./docs/index.rst.
extensions = [
'sphinx_rtd_theme',
'sphinx.ext.autodoc',
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.viewcode', # Eye icon at top of page to view page source code on GitHub.
'sphinx_copybutton', # Copy-to-clipboard button in code blocks & code examples.
'breathe',
'sphinx_sitemap',
'lv_example',
'sphinx_design',
'sphinx_rtd_dark_mode',
# 'link_roles',
'sphinxcontrib.mermaid',
]
@@ -116,7 +129,8 @@ del add_redirects
highlight_language = 'c'
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
pygments_style = 'github-light'
pygments_dark_style = 'github-dark'
# -------------------------------------------------------------------------
# Options for Internationalisation
@@ -141,8 +155,8 @@ primary_domain = 'c' # Default: 'py'
# List of glob-style patterns, relative to source directory, that
# match files and directories to ignore when looking for source files.
# These patterns also effect html_static_path and html_extra_path.
exclude_patterns = ['build', 'doxygen', 'Thumbs.db', '.DS_Store',
'README.md', 'README_*', 'lv_examples', 'out_html', 'env', '_ext', 'examples']
exclude_patterns = ['build', 'doxygen', 'intermediate', 'doxygen_html', 'Thumbs.db', '.DS_Store',
'README.md', 'README_*', 'lv_examples', 'env', '_ext', 'examples']
# The master toctree document. (Root of TOC tree.)
master_doc = 'index'
@@ -189,7 +203,7 @@ templates_path = ['_templates']
# Options for HTML Builder
# -------------------------------------------------------------------------
# The theme for HTML output. See https://www.sphinx-doc.org/en/master/usage/theming.html
html_theme = 'sphinx_rtd_theme'
html_theme = 'furo'
# Theme options are theme-specific and customize the look and feel of a
# theme further. For a list of options available for each theme, see the
@@ -202,18 +216,13 @@ html_theme = 'sphinx_rtd_theme'
# version of sphinx-rtd-theme (upgraded for Sphinx v8.x). The removed line
# is preserved by commenting it out in case it is ever needed again.
html_theme_options = {
# 'display_version': True,
'prev_next_buttons_location': 'both',
'style_external_links': False,
# 'vcs_pageview_mode': '',
# 'style_nav_header_background': 'white',
# Toc options
'sticky_navigation': True,
'navigation_depth': 4,
'includehidden': False,
'titles_only': False,
'collapse_navigation': False,
'logo_only': True,
"sidebar_hide_name": True, # True when the logo carries project name
"top_of_page_buttons": ["view"],
# The below 3 direct the "top_of_page_buttons" to github for view and edit buttons.
"source_repository": "https://github.com/lvgl/lvgl/",
"source_branch": "master",
"source_directory": "docs/src/",
# "announcement": "<em>Semi-permanent announcement</em> from <code>conf.py</code>.",
}
# For site map generation
@@ -247,8 +256,10 @@ html_logo = '_static/images/logo_lvgl.png'
html_favicon = '_static/images/favicon.png'
html_css_files = [
'css/custom.css',
'css/fontawesome.min.css'
'css/fontawesome.min.css',
'css/solid.min.css',
'css/brands.min.css',
'css/custom.css'
]
html_js_files = [
@@ -261,12 +272,13 @@ html_last_updated_fmt = '' # Empty string uses default format: '%b %d,
html_last_updated_use_utc = False # False = use generating system's local date, not GMT.
html_permalinks = True # Default = True, add link anchor for each heading and description environment.
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
]
}
# 10-Mar-2025 16:21 -- commented out for Furo theme.
# html_sidebars = {
# '**': [
# 'relations.html', # needs 'show_related': True theme option to display
# 'searchbox.html',
# ]
# }
# html_domain_indices
# html_use_index = True # Default = True
docs/src/index.rst
+5 -4
View File
@@ -93,10 +93,11 @@ Appendix
entries in the top-level navigation tree. (This is the only toctree directive
with the :hidden: attribute.)
.. toctree::
:hidden:
.. Commenting out the below for Furo theme.
.. toctree::
:hidden:
intro/index
details/index
intro/index
details/index