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

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.

docs/build.py

@@ -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

@@ -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/custom.css

@@ -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
+ * Version Dropdown Styling
- * `sphinx_rtd_theme` `layout.html` template.
+ *-------------------------------------------------------------------------*/
- *-------------------------------------------------------------------------
+#version_dropdown {
- * `wy-side-nav-search` class adorns the <div> element in the upper left
+  background-color: var(--color-sidebar-background);
- * corner of each page that contains:
+  color: var(--color-foreground-primary);
- * - the LVGL logo
+  margin: 4px 0;
- * - documentation-version selector drop-down (matches LVGL release versions)
+  width: 150px;
- * - search TextBox
+  border-radius: 5px;
- */
-.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
 }
 
 /*-------------------------------------------------------------------------
@@ -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

@@ -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/_templates/layout.html

@@ -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

@@ -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);
+            const version_list = text.split("\n").filter(version => version.trim().length > 0);
-            let p = document.getElementById("rtd-search-form").parentElement;
+            /* Note:  class "sidebar-search-container" is part of Furo theme. */
-            p.innerHTML = `
+            let srch_form = document.getElementsByClassName("sidebar-search-container")[0];
-            <select name="versions" id="versions" onchange="ver_sel()" style="border-radius:5px; margin-bottom:15px">
+            let parent_div = srch_form.parentElement;
-            ${versions.map(version => {
+
-                let versionName = "";
+            let select_elem_text = `
-                if(version == "master") versionName = "master (latest)";
+                <select name="version" id="version_dropdown" onchange="ver_sel()">
-                else versionName = "v" + ((version.indexOf(".") != -1) ? version : (version + " (latest minor)"));
+                ${version_list.map(version => {
-                return `<option value="${version}">${versionName}</option>`;
+                    let versionName = "";
-            })}
+                    if(version == "master") versionName = "master (latest)";
-            </select>` + p.innerHTML;
+                    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;
+  var x = document.getElementById("version_dropdown").value;
-  window.location.href = window.location.protocol + "//" + window.location.host + "/" + x + "/";
+  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

@@ -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_src_path = os.path.join(base_path, cfg_lv_version_file)
-version = lvgl_version(version_src_path)
+
+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',
+exclude_patterns = ['build', 'doxygen', 'intermediate', 'doxygen_html', 'Thumbs.db', '.DS_Store',
-                    'README.md', 'README_*', 'lv_examples', 'out_html', 'env', '_ext', 'examples']
+                    '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,
+    "sidebar_hide_name": True,      # True when the logo carries project name
-    'prev_next_buttons_location': 'both',
+    "top_of_page_buttons": ["view"],
-    'style_external_links': False,
+    # The below 3 direct the "top_of_page_buttons" to github for view and edit buttons.
-    # 'vcs_pageview_mode': '',
+    "source_repository": "https://github.com/lvgl/lvgl/",
-    # 'style_nav_header_background': 'white',
+    "source_branch": "master",
-    # Toc options
+    "source_directory": "docs/src/",
-    'sticky_navigation': True,
+    # "announcement": "<em>Semi-permanent announcement</em> from <code>conf.py</code>.",
-    'navigation_depth': 4,
-    'includehidden': False,
-    'titles_only': False,
-    'collapse_navigation': False,
-    'logo_only': True,
 }
 
 # 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 = {
+# 10-Mar-2025 16:21 -- commented out for Furo theme.
-    '**': [
+# html_sidebars = {
-        'relations.html',  # needs 'show_related': True theme option to display
+#     '**': [
-        'searchbox.html',
+#         '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

@@ -93,10 +93,11 @@ Appendix
    entries in the top-level navigation tree.  (This is the only toctree directive
    with the :hidden: attribute.)
 
-.. toctree::
+.. Commenting out the below for Furo theme.
-    :hidden:
+    .. toctree::
+        :hidden:
 
-    intro/index
+        intro/index
-    details/index
+        details/index