docs(restructure): restructure TOC and contents for ease of use (#7847)

.github/workflows/compile_docs.yml

@@ -66,7 +66,7 @@ jobs:
       - name: Build docs
         run: docs/build.py html
       - name: Remove .doctrees
-        run: rm -rf docs/output/html/.doctrees
+        run: rm -rf docs/build/html/.doctrees
       - name: Retrieve version
         run: |
           echo "::set-output name=VERSION_NAME::$(scripts/find_version.sh)"
@@ -77,7 +77,7 @@ jobs:
           token: ${{ secrets.LVGL_BOT_TOKEN }}
           repository-name: lvgl/docs
           branch: gh-pages # The branch the action should deploy to.
-          folder: docs/output/html  # The folder the action should deploy.
+          folder: docs/build/html  # The folder the action should deploy.
           target-folder: ${{ steps.version.outputs.VERSION_NAME }}
           git-config-name: lvgl-bot
           git-config-email: lvgl-bot@users.noreply.github.com
@@ -89,7 +89,7 @@ jobs:
           token: ${{ secrets.LVGL_BOT_TOKEN }}
           repository-name: lvgl/docs
           branch: gh-pages # The branch the action should deploy to.
-          folder: docs/output/html  # The folder the action should deploy.
+          folder: docs/build/html  # The folder the action should deploy.
           target-folder: master
           git-config-name: lvgl-bot
           git-config-email: lvgl-bot@users.noreply.github.com

docs/.gitignore

@@ -1,11 +1,2 @@
-output/
-tmp/
-xml/
-API/
-api_doc
-doxygen_html
-env
-examples.md
-examples.rst
-LVGL.pdf
-_static/built_lv_examples
+build/
+intermediate/

docs/CONTRIBUTING.rst

@@ -1,235 +0,0 @@
-.. _contributing:
-
-============
-Contributing
-============
-
-Introduction
-************
-
-Join LVGL's community and leave your footprint in the library!
-
-There are a lot of ways to contribute to LVGL even if you are new to the
-library or even new to programming.
-
-It might be scary to make the first step but you have nothing to be
-afraid of. A friendly and helpful community is waiting for you. Get to
-know like-minded people and make something great together.
-
-So let's find which contribution option fits you the best and helps you
-join the development of LVGL!
-
-Ways to Contribute
-******************
-
-- **Spread the Word**: Share your LVGL experience with friends or on social media to boost its visibility.
-- **Star LVGL**   Give us a star on `GitHub <https://github.com/lvgl/lvgl>`__! It helps a lot to make LVGL more appealing for newcomers.
-- **Report a Bug**: Open a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__ if something is not working.
-- **Join Our** `Forum <https://forum.lvgl.io/>`__ : Meet fellow developers and discuss questions.
-- **Tell Us Your Ideas**: If you feel something is missing from LVGL, we would love to hear about it in a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__
-- **Develop Features**: Help to design or develop a feature. See below.
-
-Mid- and large-scale issues are discussed in `Feature Planning <https://github.com/lvgl/lvgl/issues/new?assignees=&labels=&projects=&template=feat-planning.yml>`__ issues.
-
-An issue can be developed when all the questions in the issue template are answered and there are no objection from any core member.
-
-We are using GitHub labels to show the state and attributes of the issues and Pull requests.
-If you are looking for contribution opportunities you can `Filter for these labels <https://github.com/lvgl/lvgl/labels>`__ :
-
-- ``Simple``: Good choice to get started with an LVGL contribution
-- ``PR needed``: We investigated the issue but it still needs to be implemented
-- ``Review needed``: A Pull request is opened and it needs review/testing
-
-
-.. _contributing_pull_requests:
-
-Pull Requests
-*************
-
-Merging new code into LVGL, documentation, blog, examples, and other
-repositories happens via *Pull requests* (PR for short). A PR is a
-notification like "Hey, I made some updates to your project. Here are
-the changes, you can add them if you want." To do this you need a copy
-(called fork) of the original project under your account, make some
-changes there, and notify the original repository about your updates.
-You can see what it looks like on GitHub for LVGL here:
-https://github.com/lvgl/lvgl/pulls.
-
-To add your changes you can edit files online on GitHub and send a new
-Pull request from there (recommended for small changes) or add the
-updates in your favorite editor/IDE and use ``git`` to publish the changes
-(recommended for more complex updates).
-
-From GitHub
------------
-
-1. Navigate to the file you want to edit.
-2. Click the Edit button in the top right-hand corner.
-3. Add your changes to the file.
-4. Add a commit message at the bottom of the page.
-5. Click the *Propose changes* button.
-
-From Command Line
------------------
-
-The instructions describe the main ``lvgl`` repository but it works the
-same way for the other repositories.
-
-1. Fork the `lvgl repository <https://github.com/lvgl/lvgl>`__. To do this click the
-   "Fork" button in the top right corner. It will "copy" the ``lvgl``
-   repository to your GitHub account (``https://github.com/<YOUR_NAME>?tab=repositories``)
-2. Clone your forked repository.
-3. Add your changes. You can create a *feature branch* from THE ``master`` branch for the updates: ``git checkout -b <new-feature-branch-name>``
-4. Commit and push your changes to the forked ``lvgl`` repository.
-5. Create a PR on GitHub from the page of your ``lvgl`` repository (``https://github.com/<YOUR_NAME>/lvgl``) by
-   clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes.
-6. Set the base branch where you want to merge your update. In the ``lvgl`` repo both fixes
-   and new features are directed to the ``master`` branch.
-7. Describe what is in the update. Example code is welcome if applicable.
-8. If you need to make more changes, just update your forked ``lvgl`` repo with new commits.
-   They will automatically appear in the PR.
-
-.. _contributing_commit_message_format:
-
-Commit Message Format
----------------------
-
-The commit messages format is inspired by `Angular Commit
-Format <https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit>`__.
-
-The following structure should be used:
-
-.. code-block::
-
-   <type>(<scope>): <subject>
-   <BLANK LINE>
-   <body>
-   <BLANK LINE>
-   <footer>
-
-Possible ``<type>``\ s:
-
-- ``fix`` bugfix in LVGL source code
-- ``feat`` new feature
-- ``arch`` architectural changes
-- ``perf`` changes that affect performance
-- ``example`` anything related to examples (including fixes and new examples)
-- ``docs`` anything related to documentation (including fixes, formatting, and new pages)
-- ``test`` anything related to tests (new and updated tests or CI actions)
-- ``chore`` any minor formatting or style changes that would make the changelog noisy
-
-``<scope>`` is the name of the module, file, or subsystem affected by the
-commit. It's usually one word and can be chosen freely. For example
-``img``, ``layout``, ``txt``, ``anim``. The scope can be omitted.
-
-``<subject>`` contains a short description of the change:
-
-- use the imperative, present tense: "change" not "changed" nor "changes",
-- don't capitalize the first letter,
-- no period (``.``) at the end,
-- max 90 characters.
-
-``<body>`` optional and can be used to describe details of the
-change.
-
-``<footer>`` shall contain
-
-- the words "BREAKING CHANGE" if the changes break the API
-- reference to the GitHub issue or Pull Request if applicable.
-  (See `Linking a pull rquest to an issue <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue>`__
-  for details.)
-
-Some examples:
-
-.. code-block:: text
-
-    fix(image): update size when a new source is set
-
-.. code-block:: text
-
-    fix(bar): fix memory leak
-
-    The animations weren't deleted in the destructor.
-
-    Fixes: #1234
-
-.. code-block:: text
-
-    feat: add span widget
-
-    The span widget allows mixing different font sizes, colors and styles.
-    It's similar to HTML <span>
-
-.. code-block:: text
-
-    docs(porting): fix typo
-
-
-
-.. _contributing_dco:
-
-Developer Certification of Origin (DCO)
-***************************************
-
-Overview
---------
-
-To ensure all licensing criteria are met for every repository of the
-LVGL project, we apply a process called DCO (Developer's Certificate of
-Origin).
-
-The text of DCO can be read here: https://developercertificate.org/.
-
-By contributing to any repositories of the LVGL project you agree that
-your contribution complies with the DCO.
-
-If your contribution fulfills the requirements of the DCO, no further
-action is needed. If you are unsure feel free to ask us in a comment,
-e.g. in your submitted :ref:`Pull Request <contributing_pull_requests>`.
-
-Accepted licenses and copyright notices
----------------------------------------
-
-To make the DCO easier to digest, here are some practical guides about
-specific cases:
-
-Your own work
-~~~~~~~~~~~~~
-
-The simplest case is when the contribution is solely your own work. In
-this case you can just send a Pull Request without worrying about any
-licensing issues.
-
-Use code from online source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the code you would like to add is based on an article, post or
-comment on a website (e.g. StackOverflow) the license and/or rules of
-that site should be followed.
-
-For example in case of StackOverflow, a notice like this can be used:
-
-.. code-block::
-
-   /* The original version of this code-snippet was published on StackOverflow.
-    * Post: http://stackoverflow.com/questions/12345
-    * Author: http://stackoverflow.com/users/12345/username
-    * The following parts of the snippet were changed:
-    * - Check this or that
-    * - Optimize performance here and there
-    */
-    ... code snippet here ...
-
-Use MIT licensed code
-~~~~~~~~~~~~~~~~~~~~~
-
-As LVGL is MIT licensed, other MIT licensed code can be integrated
-without issues. The MIT license requires a copyright notice be added to
-the derived work. Any derivative work based on MIT licensed code must
-copy the original work's license file or text.
-
-Use GPL licensed code
-~~~~~~~~~~~~~~~~~~~~~
-
-The GPL license is not compatible with the MIT license. Therefore, LVGL
-cannot accept GPL licensed code.

docs/Makefile

@@ -0,0 +1,30 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+BUILDDIR      = build
+SOURCEDIR     = intermediatex
+
+# SOURCEDIR can be overridden by LVGL_DOC_BUILD_INTERMEDIATE_DIR
+LEN           := $(shell printf '%s' '$(LVGL_DOC_BUILD_INTERMEDIATE_DIR)' | wc -c)
+
+ifeq ($(shell test $(LEN) -gt 0; echo $$?),0)
+	SOURCEDIR = $(LVGL_DOC_BUILD_INTERMEDIATE_DIR)
+else
+	SOURCEDIR = intermediate
+endif
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# It can be supplied from an environment variable 'O' or on make command line.
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/ROADMAP.rst

@@ -1,182 +0,0 @@
-
-.. |check| replace:: ☑️
-
-.. |uncheck| replace:: 🔲
-
-.. _roadmap:
-
-Roadmap
-=======
-
-v9
---
-
-Schedule
-~~~~~~~~
-
-- December 4: Feature stop, start updating the docs and testing
-- December 18: Release candidate version and call to test
-- January 15: Release v9.0
-
-Naming and API
-~~~~~~~~~~~~~~
-
-- |check| `lv_style_set_size()` should have separate width and height parameters
-- |check| Reconsider image color formats.
-- |check| More consistent names:`remove/clear/delete/del`, `offset/ofs`, `add/create/register`, `id/idx/index`, `middle/mid/center`, `img/image`, `txt/text`, `opa/opacity/alpha`, `scr/screen`, `disp, display`, `finished/complete/completed/ready`, `buf/buffer`,  `..._cb`, `angle/rotation`, `zoom/scale`, `has`, `is`, `enable`
-- |check| Update canvas API `LINK <https://github.com/lvgl/lvgl/issues/3393>`__
-- |check| `LV_STYLE_PROP_INHERIT` -> `LV_STYLE_PROP_FLAG_INHERITABLE`
-  `LINK <https://github.com/lvgl/lvgl/pull/3390#discussion_r885915769>`__
-- |check| Replace `disp_drv->direct_mode/full_refresh` with enum.
-- |check| Consider flat directory structure. E.g. `extra/widgets` to `widgets`
-- |check| Use `uint32_t` and `int32_t` in APIs where possible. Consider hardcoding `int32_t` as `int32_t`.
-- |check| To define a new stdlib API use defines `LV_USE_CUSTOM_...` and
-  let the user implement `lv_...` functions somewhere (instead of defining the name of the custom functions)
-  (see `here <https://github.com/lvgl/lvgl/issues/3481#issuecomment-1206434501>`__)
-- |check| Gradient with alpha
-
-Architecture
-~~~~~~~~~~~~
-
-- |check| Consider merging `lv_disp_drv_t`, `lv_disp_t`, `lv_disp_draw_buf_t`, `lv_draw_ctx_t` `struct`'s from the new driver API (or only some of them)
-- |check| New driver architecture #2720
-- |check| `draw_ctx->buffer_convert`?
-  (see `here <https://github.com/lvgl/lvgl/issues/3379#issuecomment-1147954592>`__)
-  Also remove 16 SWAPPED color format?
-  (see `here <https://github.com/lvgl/lvgl/issues/3379#issuecomment-1140886258>`__)
-- |check| Reconsider masks. There should be a generic high level mask API which is independent of the drawing engine.
-  `#4059 <https://github.com/lvgl/lvgl/issues/4059>`__
-- |check| `get_glyph_bitmap` should return an a8 bitmap that can be blended immediately.
-  (see `here <https://github.com/lvgl/lvgl/pull/3390#pullrequestreview-990710921>`__)
-- |check| Make LVGL render independent areas in parallel.
-  `#4016 <https://github.com/lvgl/lvgl/issues/4016>`__
-- |check| Drop `lv_mem_buf_get` as tlsf should be fast enough for normal allocations as well.
-  Fragmentation is also lower if processes can completely clean up after themselves.
-- |check| More color formats: 24 bit, ARGB1555, ARGB4444 etc
-  (see `here <https://forum.lvgl.io/t/keypad-input-device-why-lv-event-long-pressed-only-on-enter/10263>`__)
-- |check| Unified caching #3116 #3415
-- |check| Variable binding. I.e create properties which can be bound to Widgets and those Widgets are notified on value change. Maybe based on `lv_msg`?
-- |uncheck| Add GPU abstraction for display rotation
-- |check| Replace the `read_line_cb` of the image decoders with `get_area_cb`
-- |check| Limit the image caching size in bytes instead of image count
-- |check| lv_draw_buf for unified stride, buffer and cache invalidation management. `4241 <https://github.com/lvgl/lvgl/pull/4241>`__
-- |check| Add vector graphics support via ThorVG
-- |check| SVG support: integrate an SVG render library `4388 <https://github.com/lvgl/lvgl/issues/4388>`__
-- |check| Introduce optional ``float`` support. `4648 <https://github.com/lvgl/lvgl/issues/4648>`__
-- |check| Introduce support layer for 3D GPUs (OpenGL, SDL, Vulkan, etc).  `4622 <https://github.com/lvgl/lvgl/issues/4622>`__
-
-Styles
-~~~~~~
-
-- |check| non-uniform scale of images: scale width and height differently
-- |check| Scroll anim settings should come from styles to allow customization
-
-Widgets
-~~~~~~~
-
-- |check| Universal scale widget/support
-- |check| `lv_img`: Reconsider image sizing models
-  (when the image size is not content): center, top-left, zoom, tile, other?
-- |check| `lv_tabview` Replace button matrix with real buttons for more flexibility
-  (see `here <https://forum.lvgl.io/t/linear-meter-bar-with-ticks/10986>`__ and #4043)
-- |check| Disabled widgets should absorb indev actions without sending events. `#3860 <https://github.com/lvgl/lvgl/issues/3860>`__
-
-Animations
-~~~~~~~~~~
-
-- |check| `lv_anim_time_to_speed` should work differently to remove
-  `style_anim_speed`. E.g. on large values of anim time store the
-  speed. Besides all widgets should use the `style_anim` property.
-  `anim` should clamp the time if it's calculated from speed, e.g
-  `lv_clamp(200, t, 2000)`. (maybe `a->min_time/max_time`).
-- |uncheck| Use dedicated `lv_anim_custom_exec_cb_t`.
-  See `here <https://forum.lvgl.io/t/custom-exec-cb-prevents-lv-anim-del-obj-null/10266>`__.
-
-Planned in general
-------------------
-
-CI
-~~
-
-- |uncheck| Platform independent benchmarking #3443
-- |uncheck| Run static analyzer
-- |uncheck| Release script
-- |uncheck| Unit test for all widgets #2337
-- |uncheck| CI test for flash/RAM usage #3127
-
-
-Architecture
-~~~~~~~~~~~~
-
-- |uncheck| Add more feature to key presses (long press, release, etc).
-- |uncheck| `lv_image_set_src()` use “type-aware” parameter and rework image decoders.
-  (see `here <https://github.com/lvgl/lvgl/tree/arch/img-decode-rework>`__)
-- |uncheck| `C++ binding <https://github.com/lvgl/lv_binding_cpp>`__
-- |uncheck| Markup language #2428
-
-
-Styles
-~~~~~~
-
-- |uncheck| Hover
-- |uncheck| Global states in selectors. E.g. `LV_STATE_PRESSED | SMALL_SCREEN` like media quarry in CSS
-
-
-Drawing and rendering
-~~~~~~~~~~~~~~~~~~~~~
-
-- |uncheck| SW: Line drawing with image rotation
-- |uncheck| SW: Arc drawing from small squares (16x16?) to detect transparent or solid parts
-- |uncheck| SW: Rounded rectangle drawing from small squares (16x16?) to detect transparent or solid parts
-- |uncheck| Different radius on each corner #2800
-- |uncheck| Gradient to border/outline/shadow
-- |uncheck| Multiple shadow/border
-- |uncheck| Perspective
-- |uncheck| Text shadow
-- |uncheck| Inner shadow
-- |uncheck| ARGB image stroke/grow on the alpha map
-- |uncheck| Real time blur
-
-
-Widgets
-~~~~~~~
-
-- |uncheck| `lv_bar`, `lv_arc`: handle max < min for fill direction swapping #4039
-- |uncheck| `lv_bar`, `lv_slider`, `lv_arc`: make possible to move the knob only inside the background (see `here <https://forum.lvgl.io/t/slider-knob-out-of-the-track/11956>`__)
-- |uncheck| Improve `lv_label_align_t` #1656
-- |uncheck| `lv_label` reconsider label long modes. (support min/max-width/height as well) #3420
-- |uncheck| `lv_roller` make it more flexible #4009
-
-Others
-~~~~~~
-- |uncheck| `em`, `ch`, `vw/vh` units
-- |uncheck| `aspect-ratio` as size
-- |uncheck| More grid features. E.g. repeat(auto-fill, minmax( px, 1fr))
-- |uncheck| Named grid cells to allow updating layouts without touching the children (like CSS `grid-template-areas`)
-- |uncheck| Scene support. See `this comment <https://github.com/lvgl/lvgl/issues/2790#issuecomment-965100911>`__
-- |uncheck| Circle layout. #2871
-- |uncheck| Consider `stagger animations <https://greensock.com/docs/v3/Staggers>`__.
-- |uncheck| Add custom indev type. See `here <https://github.com/lvgl/lvgl/issues/3298#issuecomment-1616706654>`__.
-- |uncheck| Automatically recalculate the layout if a coordinate is obtained using `lv_obj_get_width/height/x/y/etc`
-
-Ideas
------
-- Reconsider how themes should work.
-- Better way to reset global variables in `lv_deinit()` #3385
-- `lv_array`: replace linked lists with array where possible (arrays are faster and uses less memory)
-- Reconsider how to handle UTF-8 characters (allow different encoding as well) and Bidi. Maybe create an abstraction for textshaping.
-- Consider direct binary font format support
-- Improve groups. `Discussion <https://forum.lvgl.io/t/lv-group-tabindex/2927/3>`__.
-  Reconsider focusing logic. Allow having no widget selected (on web it's possible). Keep editing state in `lv_obj_t`
-  (see `here <https://github.com/lvgl/lvgl/issues/3646>`__). Support slider
-  left knob focusing (see `here <https://github.com/lvgl/lvgl/issues/3246>`__)
-- Speed up font decompression
-- Support larger images: add support for large image #1892
-- Functional programming support, pure view?
-  (see `here <https://www.freecodecamp.org/news/the-revolution-of-pure-views-aed339db7da4/>`__)
-- Style components. (see `this comment <https://github.com/lvgl/lvgl/issues/2790#issuecomment-965100911>`__
-- Support dot_begin and dot_middle long modes for labels
-- Allow matrix input for image transformation?
-- Radial/skew/conic gradient
-- Somehow let children inherit the parent's state
-- Text on path

docs/build.py

@@ -5,9 +5,9 @@ Synopsis
 --------
     - $ python build.py html  [ skip_api ] [ fresh_env ]
     - $ python build.py latex [ skip_api ] [ fresh_env ]
-    - $ python build.py temp  [ skip_api ]
+    - $ python build.py intermediate  [ skip_api ]
     - $ python build.py clean
-    - $ python build.py clean_temp
+    - $ python build.py clean_intermediate
     - $ python build.py clean_html
     - $ python build.py clean_latex
 
@@ -16,23 +16,26 @@ Synopsis
 
 Description
 -----------
-    Source files are copied to a temporary directory and modified there before
+    Copy source files to an intermediate directory and modify them there before
     doc generation occurs.  If a full rebuild is being done (e.g. after a `clean`)
-    Doxygen is run on LVGL's source files to generate intermediate API information
-    in XML format, example documents are generated, API documents are generated
-    for Breathe's consumption, and API links are added to the end of some documents.
-    From there, Sphinx with Breathe extension uses the resulting set of source
-    files to generate the desired output.
+    run Doxygen LVGL's source files to generate intermediate API information
+    in XML format.  Generate API documents for Breathe's consumption.  Add API
+    links to end of some documents.  Generate example documents.  From there,
+    Sphinx with Breathe extension uses the resulting set of intermediate files
+    to generate the desired output.
 
     It is only during this first build that the `skip_api` option has meaning.
     After the first build, no further actions is taken regarding API pages since
     they are not regenerated after the first build.
 
-    The temporary directory has a fixed location (overridable by
-    `LVGL_DOC_BUILD_TEMP_DIR` environment variable) and by default this
+    The intermediate directory has a fixed location (overridable by
+    `LVGL_DOC_BUILD_INTERMEDIATE_DIR` environment variable) and by default this
     script attempts to rebuild only those documents whose path, name or
     modification date has changed since the last build.
 
+    The output directory also has a fixed location (overridable by
+    `LVGL_DOC_BUILD_OUTPUT_DIR` environment variable).
+
     Caution:
 
     The document build meant for end-user consumption should ONLY be done after a
@@ -40,12 +43,12 @@ Description
 
     A `sphinx-build` will do a full doc rebuild any time:
 
-    - the temporary directory doesn't exist or is empty (since the new files in
-      the temporary directory will have modification times after the generated
+    - the intermediate directory doesn't exist or is empty (since the new files in
+      the intermediate directory will have modification times after the generated
       HTML or Latex files, even if nothing changed),
     - the targeted output directory doesn't exist or is empty, or
     - Sphinx determines that a full rebuild is necessary.  This happens when:
-        - temporary directory (Sphinx's source-file path) has changed,
+        - intermediate directory (Sphinx's source-file path) has changed,
         - any options on the `sphinx-build` command line have changed,
         - `conf.py` modification date has changed, or
         - `fresh_env` argument is included (runs `sphinx-build` with -E option).
@@ -62,21 +65,22 @@ Options
 
     html [ skip_api ] [ fresh_env ]
         Build HTML output.
-        `skip_api` only has effect on first build after a `clean` or `clean_temp`.
+        `skip_api` only has effect on first build after a `clean` or `clean_intermediate`.
 
     latex [ skip_api ] [ fresh_env ]
         Build Latex/PDF output (on hold pending removal of non-ASCII characters from input files).
-        `skip_api` only has effect on first build after a `clean` or `clean_temp`.
+        `skip_api` only has effect on first build after a `clean` or `clean_intermediate`.
 
-    temp [ skip_api ]
-        Generate temporary directory contents (ready to build output formats).
+    intermediate [ skip_api ]
+        Generate intermediate directory contents (ready to build output formats).
         If they already exist, they are removed and re-generated.
+        Note:  "intermediate" can be abbreviated down to "int".
 
-    skip_api (with `html` and/or `latex` and/or `temp` options)
-        Skip API pages and links when temp directory contents are being generated
-        (saving about 91% of build time).  Note: they are not thereafter regenerated
-        unless requested by `temp` argument or the temp directory does not exist.
-        This is intended to be used only during doc development to speed up
+    skip_api (with `html` and/or `latex` and/or `intermediate` options)
+        Skip API pages and links when intermediate directory contents are being generated
+        (saving about 91% of build time).  Note: they are not thereafter regenerated unless
+        requested by `intermediate` argument or the intermediate directory does not
+        exist.  This is intended to be used only during doc development to speed up
         turn-around time between doc modifications and seeing final results.
 
     fresh_env (with `html` and/or `latex` options)
@@ -86,8 +90,9 @@ Options
     clean
         Remove all generated files.
 
-    clean_temp
-        Remove temporary directory.
+    clean_intermediate
+        Remove intermediate directory.
+        Note:  "clean_intermediate" can be abbreviated down to "clean_int".
 
     clean_html
         Remove HTML output directory.
@@ -130,20 +135,19 @@ History
 
     - Supporting additional command-line options.
 
-    - Generating a temporary `./docs/lv_conf.h` for Doxygen to use
-      (via config_builder.py).
+    - Generating a `./docs/lv_conf.h` for Doxygen to use (config_builder.py).
 
     - Supporting multiple execution platforms (which then required tokenizing
       Doxygen's INPUT path in `Doxyfile` and re-writing portions that used
       `sed` to generate input or modify files).
 
-    - Adding translation and API links (requiring generating docs in a
-      temporary directory so that the links could be programmatically
+    - Adding translation and API links (requiring generating docs in an
+      intermediate directory so that the links could be programmatically
       added to each document before Sphinx was run).  Note:  translation link
       are now done manually since they are only on the main landing page.
 
     - Generating EXAMPLES page + sub-examples where applicable to individual
-      documents, e.g. to widget-, style-, layout-pages, etc..
+      documents, e.g. to widget-, style-, layout-pages, etc.
 
     - Building PDF via latex (when working).
 
@@ -161,7 +165,6 @@ History
 # Python Library
 import sys
 import os
-import re
 import subprocess
 import shutil
 import dirsync
@@ -171,16 +174,32 @@ from datetime import datetime
 import example_list
 import doc_builder
 import config_builder
-import add_translation
+_ = os.path.abspath(os.path.dirname(__file__))
+docs_src_dir = os.path.join(_, 'src')
+sys.path.insert(0, docs_src_dir)
+from lvgl_version import lvgl_version  # NoQA
+
+# Not Currently Used
+# (Code is kept in case we want to re-implement it later.)
+# import add_translation
 
 # -------------------------------------------------------------------------
 # Configuration
 # -------------------------------------------------------------------------
 # These are relative paths from the ./docs/ directory.
-cfg_temp_dir = 'tmp'
-cfg_output_dir = 'output'
+cfg_project_dir = '..'
+cfg_src_dir = 'src'
+cfg_examples_dir = 'examples'
+cfg_default_intermediate_dir = 'intermediate'
+cfg_default_output_dir = 'build'
+cfg_static_dir = '_static'
+cfg_downloads_dir = 'downloads'
+cfg_lv_conf_filename = 'lv_conf.h'
+cfg_lv_version_filename = 'lv_version.h'
+cfg_doxyfile_filename = 'Doxyfile'
+cfg_top_index_filename = 'index.rst'
 
-# Filename generated in `cfg_latex_output_dir` and copied to `cfg_pdf_output_dir`.
+# Filename generated in `latex_output_dir` and copied to `pdf_output_dir`.
 cfg_pdf_filename = 'LVGL.pdf'
 
 
@@ -194,18 +213,16 @@ def print_usage_note():
     print('  where `optional_arg` can be any of these:')
     print('    html  [ skip_api ] [ fresh_env ]')
     print('    latex [ skip_api ] [ fresh_env ]')
-    print('    temp  [ skip_api ]')
+    print('    intermediate  [ skip_api ]')
     print('    clean')
-    print('    clean_temp')
+    print('    clean_intermediate')
     print('    clean_html')
     print('    clean_latex')
     print('    help')
 
 
-# -------------------------------------------------------------------------
-# Remove directory `tgt_dir`.
-# -------------------------------------------------------------------------
 def remove_dir(tgt_dir):
+    """Remove directory `tgt_dir`."""
     if os.path.isdir(tgt_dir):
         print(f'Removing {tgt_dir}...')
         shutil.rmtree(tgt_dir)
@@ -213,10 +230,8 @@ def remove_dir(tgt_dir):
         print(f'{tgt_dir} already removed...')
 
 
-# -------------------------------------------------------------------------
-# Run external command and abort build on error.
-# -------------------------------------------------------------------------
 def cmd(s, start_dir=None, exit_on_error=True):
+    """Run external command and abort build on error."""
     if start_dir is None:
         start_dir = os.getcwd()
 
@@ -233,91 +248,71 @@ def cmd(s, start_dir=None, exit_on_error=True):
         sys.exit(result)
 
 
-# -------------------------------------------------------------------------
-# Build and return LVGL version string from `lv_version.h`.  Updated to be
-# multi-platform compatible and resilient to changes in file in compliance
-# with C macro syntax.
-# -------------------------------------------------------------------------
-def get_version(_verfile):
-    major = ''
-    minor = ''
-
-    with open(_verfile, 'r') as file:
-        major_re = re.compile(r'define\s+LVGL_VERSION_MAJOR\s+(\d+)')
-        minor_re = re.compile(r'define\s+LVGL_VERSION_MINOR\s+(\d+)')
-
-        for line in file.readlines():
-            # Skip if line not long enough to match.
-            if len(line) < 28:
-                continue
-
-            match = major_re.search(line)
-            if match is not None:
-                major = match[1]
-            else:
-                match = minor_re.search(line)
-                if match is not None:
-                    minor = match[1]
-                    # Exit early if we have both values.
-                    if len(major) > 0 and len(minor) > 0:
-                        break
-
-    return f'{major}.{minor}'
-
-
-# -------------------------------------------------------------------------
-# Provide answer to question:  Can we have reasonable confidence that
-# the contents of `temp_directory` already exists?
-# -------------------------------------------------------------------------
-def temp_dir_contents_exists(_tmpdir):
+def intermediate_dir_contents_exists(dir):
+    """Provide answer to question:  Can we have reasonable confidence that
+    the contents of `intermediate_directory` already exists?
+    """
     result = False
-    c1 = os.path.isdir(_tmpdir)
+    c1 = os.path.isdir(dir)
 
     if c1:
-        temp_path = os.path.join(_tmpdir, 'CHANGELOG.rst')
+        temp_path = os.path.join(dir, 'CHANGELOG.rst')
         c2 = os.path.exists(temp_path)
-        temp_path = os.path.join(_tmpdir, 'CODING_STYLE.rst')
-        c3 = os.path.exists(temp_path)
-        temp_path = os.path.join(_tmpdir, 'CONTRIBUTING.rst')
-        c4 = os.path.exists(temp_path)
-        temp_path = os.path.join(_tmpdir, '_ext')
+        temp_path = os.path.join(dir, '_ext')
+        c3 = os.path.isdir(temp_path)
+        temp_path = os.path.join(dir, '_static')
+        c4 = os.path.isdir(temp_path)
+        temp_path = os.path.join(dir, 'details')
         c5 = os.path.isdir(temp_path)
-        temp_path = os.path.join(_tmpdir, '_static')
+        temp_path = os.path.join(dir, 'intro')
         c6 = os.path.isdir(temp_path)
-        temp_path = os.path.join(_tmpdir, 'details')
+        temp_path = os.path.join(dir, 'contributing')
         c7 = os.path.isdir(temp_path)
-        temp_path = os.path.join(_tmpdir, 'intro')
+        temp_path = os.path.join(dir, cfg_examples_dir)
         c8 = os.path.isdir(temp_path)
-        temp_path = os.path.join(_tmpdir, 'examples')
-        c9 = os.path.isdir(temp_path)
-        result = c2 and c3 and c4 and c5 and c6 and c7 and c8 and c9
+        result = c2 and c3 and c4 and c5 and c6 and c7 and c8
 
     return result
 
 
-# -------------------------------------------------------------------------
-# Perform doc-build function(s) requested.
-# -------------------------------------------------------------------------
-def run():
+def run(args):
+    """Perform doc-build function(s) requested."""
+
     # ---------------------------------------------------------------------
-    # Process args.
-    #
-    # With argument `docs_dev`, Sphinx will generate docs from a fixed
-    # temporary directory that can be then used later using the same
-    # command line to get Sphinx to ONLY rebuild changed documents.
-    # This saves a huge amount of time during long document projects.
+    # Set default settings.
     # ---------------------------------------------------------------------
-    # Set defaults.
-    clean_temp = False
-    clean_html = False
-    clean_latex = False
-    clean_all = False
     build_html = False
     build_latex = False
-    build_temp = False
+    build_intermediate = False
     skip_api = False
     fresh_sphinx_env = False
-    args = sys.argv[1:]
+    clean_all = False
+    clean_intermediate = False
+    clean_html = False
+    clean_latex = False
+
+    def print_setting(setting_name, val):
+        """Print one setting; used for debugging."""
+        print(f'{setting_name:18} = [{val}]')
+
+    def print_settings(and_exit):
+        """Print all settings and optionally exit; used for debugging."""
+        print_setting("build_html", build_html)
+        print_setting("build_latex", build_latex)
+        print_setting("build_intermediate", build_intermediate)
+        print_setting("skip_api", skip_api)
+        print_setting("fresh_sphinx_env", fresh_sphinx_env)
+        print_setting("clean_all", clean_all)
+        print_setting("clean_intermediate", clean_intermediate)
+        print_setting("clean_html", clean_html)
+        print_setting("clean_latex", clean_latex)
+
+        if and_exit:
+            exit(0)
+
+    # ---------------------------------------------------------------------
+    # Process args.
+    # ---------------------------------------------------------------------
 
     # No args means print usage note and exit with status 0.
     if len(args) == 0:
@@ -332,33 +327,45 @@ def run():
         if arg == 'help':
             print_usage_note()
             exit(0)
-        elif arg == "temp":
-            build_temp = True
         elif arg == "html":
             build_html = True
         elif arg == "latex":
             build_latex = True
+        elif "intermediate".startswith(arg) and len(arg) >= 3:
+            # Accept abbreviations.
+            build_intermediate = True
         elif arg == 'skip_api':
             skip_api = True
         elif arg == 'fresh_env':
             fresh_sphinx_env = True
         elif arg == "clean":
             clean_all = True
-            clean_temp = True
+            clean_intermediate = True
             clean_html = True
             clean_latex = True
-        elif arg == "clean_temp":
-            clean_temp = True
         elif arg == "clean_html":
             clean_html = True
         elif arg == "clean_latex":
             clean_latex = True
+        elif "clean_intermediate".startswith(arg) and len(arg) >= 9:
+            # Accept abbreviations.
+            # Needs to be after others so "cl" will not
+            clean_intermediate = True
         else:
             print(f'Argument [{arg}] not recognized.')
             print()
             print_usage_note()
             exit(1)
 
+    # '-E' option forces Sphinx to rebuild its environment so all docs are
+    # fully regenerated, even if not changed.
+    # Note:  Sphinx runs in ./docs/, but uses `intermediate_dir` for input.
+    if fresh_sphinx_env:
+        print("Force-regenerating all files...")
+        env_opt = '-E'
+    else:
+        env_opt = ''
+
     # ---------------------------------------------------------------------
     # Start.
     # ---------------------------------------------------------------------
@@ -366,66 +373,102 @@ def run():
 
     # ---------------------------------------------------------------------
     # Set up paths.
-    # ---------------------------------------------------------------------
-    base_path = os.path.abspath(os.path.dirname(__file__))
-    project_path = os.path.abspath(os.path.join(base_path, '..'))
-    examples_path = os.path.join(project_path, 'examples')
-    lvgl_src_path = os.path.join(project_path, 'src')
-    output_path = os.path.join(base_path, cfg_output_dir)
-    html_output_path = os.path.join(output_path, 'html')
-    latex_output_path = os.path.join(output_path, 'latex')
-    pdf_src_file = os.path.join(latex_output_path, cfg_pdf_filename)
-    pdf_dst_file = os.path.join(base_path, cfg_pdf_filename)
-    version_source_path = os.path.join(project_path, 'lv_version.h')
-
-    # Establish temporary directory.  The presence of environment variable
-    # `LVGL_DOC_BUILD_TEMP_DIR` overrides default in `cfg_temp_dir`.
     #
-    # Temporary directory is used as Sphinx source directory -- some source
-    # files are edited, some are fully generated.  Adding translation
-    # links can be done with by adding temp in:
-    # - ./docs/add_translation.py, and
-    # - ./docs/_ext/link_roles.py.
-    # Currently, translation-link editing is being suppressed since there
-    # is only 1 file that gets the link:  top-level landing page.
-    if 'LVGL_DOC_BUILD_TEMP_DIR' in os.environ:
-        temp_directory = os.environ['LVGL_DOC_BUILD_TEMP_DIR']
+    # Variable Suffixes:
+    # _filename = filename without path
+    # _path     = path leading to a file or directory (absolute or relative)
+    # _file     = path leading to a file              (absolute or relative)
+    # _dir      = path leading to a directory         (absolute or relative)
+    # ---------------------------------------------------------------------
+    base_dir = os.path.abspath(os.path.dirname(__file__))
+    project_dir = os.path.abspath(os.path.join(base_dir, cfg_project_dir))
+    examples_dir = os.path.join(project_dir, cfg_examples_dir)
+    lvgl_src_dir = os.path.join(project_dir, 'src')
+
+    # Establish intermediate directory.  The presence of environment variable
+    # `LVGL_DOC_BUILD_INTERMEDIATE_DIR` overrides default in `cfg_default_intermediate_dir`.
+    if 'LVGL_DOC_BUILD_INTERMEDIATE_DIR' in os.environ:
+        intermediate_dir = os.environ['LVGL_DOC_BUILD_INTERMEDIATE_DIR']
     else:
-        temp_directory = os.path.join(base_path, cfg_temp_dir)
+        intermediate_dir = os.path.join(base_dir, cfg_default_intermediate_dir)
 
-    html_src_path = temp_directory
-    print(f'Temporary directory:  [{temp_directory}]')
+    lv_conf_file = os.path.join(intermediate_dir, cfg_lv_conf_filename)
+    version_dst_file = os.path.join(intermediate_dir, cfg_lv_version_filename)
+    top_index_file = os.path.join(intermediate_dir, cfg_top_index_filename)
+    doxyfile_src_file = os.path.join(base_dir, cfg_doxyfile_filename)
+    doxyfile_dst_file = os.path.join(intermediate_dir, cfg_doxyfile_filename)
+    pdf_intermediate_dst_dir = os.path.join(intermediate_dir, cfg_static_dir, cfg_downloads_dir)
+    pdf_intermediate_dst_file = os.path.join(pdf_intermediate_dst_dir, cfg_pdf_filename)
+    sphinx_path_sep = '/'
+    pdf_relative_file = cfg_static_dir + sphinx_path_sep + cfg_downloads_dir + sphinx_path_sep + cfg_pdf_filename
+    pdf_link_ref_str = f'PDF Version: :download:`{cfg_pdf_filename} <{pdf_relative_file}>`'
+
+    # Establish build directory.  The presence of environment variable
+    # `LVGL_DOC_BUILD_OUTPUT_DIR` overrides default in `cfg_default_output_dir`.
+    if 'LVGL_DOC_BUILD_OUTPUT_DIR' in os.environ:
+        output_dir = os.environ['LVGL_DOC_BUILD_OUTPUT_DIR']
+    else:
+        output_dir = os.path.join(base_dir, cfg_default_output_dir)
+
+    html_output_dir = os.path.join(output_dir, 'html')
+    latex_output_dir = os.path.join(output_dir, 'latex')
+    pdf_output_dir = os.path.join(output_dir, 'pdf')
+    pdf_src_file = os.path.join(latex_output_dir, cfg_pdf_filename)
+    pdf_dst_file = os.path.join(pdf_output_dir, cfg_pdf_filename)
+    version_src_file = os.path.join(project_dir, cfg_lv_version_filename)
+
+    # Special stuff for right-aligning PDF download link.
+    # Note: this needs to be embedded in a <div> tag because the
+    # Sphinx `:download:` role causes the link to appear in a <p> tag
+    # and in HTML5, <p> tags cannot be nested!
+    cfg_right_just_para_text = """.. raw:: html
+
+    <div style="text-align: right;">"""
+    cfg_end_right_just_para_text = """.. raw:: html
+
+    </div>"""
+    # Blank lines are required due to the directives.
+    cfg_pdf_link_ref_block_str = \
+        cfg_right_just_para_text + os.linesep \
+        + os.linesep \
+        + pdf_link_ref_str + os.linesep + \
+        os.linesep \
+        + cfg_end_right_just_para_text + os.linesep \
+        + os.linesep
 
     # ---------------------------------------------------------------------
-    # Change to script directory for consistency.
+    # Change to script directory for consistent run-time environment.
     # ---------------------------------------------------------------------
-    os.chdir(base_path)
+    os.chdir(base_dir)
+    print(f'Intermediate dir:  [{intermediate_dir}]')
+    print(f'Output dir      :  [{output_dir}]')
+    print(f'Running from    :  [{base_dir}]')
 
     # ---------------------------------------------------------------------
     # Clean?  If so, clean (like `make clean`), but do not exit.
     # ---------------------------------------------------------------------
-    some_cleaning_to_be_done = clean_temp or clean_html or clean_latex or clean_all \
-        or (os.path.isdir(temp_directory) and build_temp)
+    some_cleaning_to_be_done = clean_intermediate or clean_html or clean_latex \
+        or clean_all or (os.path.isdir(intermediate_dir) and build_intermediate)
 
     if some_cleaning_to_be_done:
         print("****************")
         print("Cleaning...")
         print("****************")
 
-        if clean_temp:
-            remove_dir(temp_directory)
+        if clean_intermediate:
+            remove_dir(intermediate_dir)
 
         if clean_html:
-            remove_dir(html_output_path)
+            remove_dir(html_output_dir)
 
         if clean_latex:
-            remove_dir(latex_output_path)
+            remove_dir(latex_output_dir)
 
         if clean_all:
-            remove_dir(output_path)
+            remove_dir(output_dir)
 
-        if os.path.isdir(temp_directory) and build_temp:
-            remove_dir(temp_directory)
+        if os.path.isdir(intermediate_dir) and build_intermediate:
+            remove_dir(intermediate_dir)
 
     # ---------------------------------------------------------------------
     # Populate LVGL_URLPATH and LVGL_GITCOMMIT environment variables:
@@ -484,16 +527,18 @@ def run():
     os.environ['LVGL_GITCOMMIT'] = branch
 
     # ---------------------------------------------------------------------
-    # Copy files to 'temp_directory' where they will be edited (translation
+    # Copy files to 'intermediate_dir' where they will be edited (translation
     # link(s) and API links) before being used to generate new docs.
     # ---------------------------------------------------------------------
     # dirsync `exclude_list` = list of regex patterns to exclude.
-    exclude_list = [r'lv_conf\.h', r'^tmp.*', r'^output.*']
+    intermediate_re = r'^' + cfg_default_intermediate_dir + r'.*'
+    output_re = r'^' + cfg_default_output_dir + r'.*'
+    exclude_list = [r'lv_conf\.h', r'^__pycache__.*', intermediate_re, output_re]
 
-    if temp_dir_contents_exists(temp_directory):
-        # We are just doing an update of the temp_directory contents.
+    if intermediate_dir_contents_exists(intermediate_dir):
+        # We are just doing an update of the intermediate_dir contents.
         print("****************")
-        print("Updating temp directory...")
+        print("Updating intermediate directory...")
         print("****************")
 
         exclude_list.append(r'examples.*')
@@ -506,12 +551,12 @@ def run():
         }
         # action == 'sync' means copy files even when they do not already exist in tgt dir.
         # action == 'update' means DO NOT copy files when they do not already exist in tgt dir.
-        dirsync.sync('.', temp_directory, 'sync', **options)
-        dirsync.sync(examples_path, os.path.join(temp_directory, 'examples'), 'sync', **options)
-    elif build_temp or build_html or build_latex:
-        # We are having to create the temp_directory contents by copying.
+        dirsync.sync(cfg_src_dir, intermediate_dir, 'sync', **options)
+        dirsync.sync(examples_dir, os.path.join(intermediate_dir, cfg_examples_dir), 'sync', **options)
+    elif build_intermediate or build_html or build_latex:
+        # We are having to create the intermediate_dir contents by copying.
         print("****************")
-        print("Building temp directory...")
+        print("Building intermediate directory...")
         print("****************")
 
         copy_method = 1
@@ -521,9 +566,9 @@ def run():
             # --------- Method 0:
             ignore_func = shutil.ignore_patterns('tmp*', 'output*')
             print('Copying docs...')
-            shutil.copytree('.', temp_directory, ignore=ignore_func, dirs_exist_ok=True)
+            shutil.copytree(cfg_src_dir, intermediate_dir, ignore=ignore_func, dirs_exist_ok=True)
             print('Copying examples...')
-            shutil.copytree(examples_path, os.path.join(temp_directory, 'examples'), dirs_exist_ok=True)
+            shutil.copytree(examples_dir, os.path.join(intermediate_dir, cfg_examples_dir), dirs_exist_ok=True)
         else:
             # --------- Method 1:
             options = {
@@ -533,26 +578,29 @@ def run():
             # action == 'sync' means copy files even when they do not already exist in tgt dir.
             # action == 'update' means DO NOT copy files when they do not already exist in tgt dir.
             print('Copying docs...')
-            dirsync.sync('.', temp_directory, 'sync', **options)
+            dirsync.sync(cfg_src_dir, intermediate_dir, 'sync', **options)
             print('Copying examples...')
-            dirsync.sync(examples_path, os.path.join(temp_directory, 'examples'), 'sync', **options)
+            dirsync.sync(examples_dir, os.path.join(intermediate_dir, cfg_examples_dir), 'sync', **options)
 
         # -----------------------------------------------------------------
         # Build Example docs, Doxygen output, API docs, and API links.
         # -----------------------------------------------------------------
         t1 = datetime.now()
 
-        # Build local lv_conf.h from lv_conf_template.h for this build only.
-        config_builder.run()
+        # Build <intermediate_dir>/lv_conf.h from lv_conf_template.h for this build only.
+        config_builder.run(lv_conf_file)
 
-        # Replace tokens in Doxyfile in 'temp_directory' with data from this run.
-        with open(os.path.join(temp_directory, 'Doxyfile'), 'rb') as f:
+        # Copy `lv_version.h` into intermediate directory.
+        shutil.copyfile(version_src_file, version_dst_file)
+
+        # Replace tokens in Doxyfile in 'intermediate_dir' with data from this run.
+        with open(doxyfile_src_file, 'rb') as f:
             data = f.read().decode('utf-8')
 
-        data = data.replace('<<LV_CONF_PATH>>', os.path.join(base_path, 'lv_conf.h'))
-        data = data.replace('<<SRC>>', '"{0}"'.format(lvgl_src_path))
+        data = data.replace('<<LV_CONF_PATH>>', lv_conf_file)
+        data = data.replace('<<SRC>>', f'"{lvgl_src_dir}"')
 
-        with open(os.path.join(temp_directory, 'Doxyfile'), 'wb') as f:
+        with open(doxyfile_dst_file, 'wb') as f:
             f.write(data.encode('utf-8'))
 
         # -----------------------------------------------------------------
@@ -560,18 +608,19 @@ def run():
         # in individual documents where applicable.
         # -----------------------------------------------------------------
         print("Generating examples...")
-        example_list.exec(temp_directory)
+        example_list.exec(intermediate_dir)
 
         # -----------------------------------------------------------------
         # Add translation links.
         # This is being skipped in favor of a manually-placed
         # translation link at the top of `./docs/index.rst`.
         # -----------------------------------------------------------------
-        if True:
-            print("Skipping adding translation links.")
-        else:
-            print("Adding translation links...")
-            add_translation.exec(temp_directory)
+        # Original code:
+        # if True:
+        #     print("Skipping adding translation links.")
+        # else:
+        #     print("Adding translation links...")
+        #     add_translation.exec(intermediate_dir)
 
         # ---------------------------------------------------------------------
         # Generate API pages and links thereto.
@@ -580,7 +629,7 @@ def run():
             print("Skipping API generation as requested.")
         else:
             print("Running Doxygen...")
-            cmd('doxygen Doxyfile', temp_directory)
+            cmd('doxygen Doxyfile', intermediate_dir)
 
             print("API page and link processing...")
             doc_builder.EMIT_WARNINGS = False
@@ -588,37 +637,37 @@ def run():
             # Create .RST files for API pages, plus
             # add API hyperlinks to .RST files in the directories in passed array.
             doc_builder.run(
-                project_path,
-                temp_directory,
-                os.path.join(temp_directory, 'intro'),
-                os.path.join(temp_directory, 'intro', 'add-lvgl-to-your-project'),
-                os.path.join(temp_directory, 'details'),
-                os.path.join(temp_directory, 'details', 'base-widget'),
-                os.path.join(temp_directory, 'details', 'base-widget', 'layouts'),
-                os.path.join(temp_directory, 'details', 'base-widget', 'styles'),
-                os.path.join(temp_directory, 'details', 'debugging'),
-                os.path.join(temp_directory, 'details', 'integration'),
-                os.path.join(temp_directory, 'details', 'integration', 'bindings'),
-                os.path.join(temp_directory, 'details', 'integration', 'building'),
-                os.path.join(temp_directory, 'details', 'integration', 'chip'),
-                os.path.join(temp_directory, 'details', 'integration', 'driver'),
-                os.path.join(temp_directory, 'details', 'integration', 'driver', 'display'),
-                os.path.join(temp_directory, 'details', 'integration', 'driver', 'touchpad'),
-                os.path.join(temp_directory, 'details', 'integration', 'framework'),
-                os.path.join(temp_directory, 'details', 'integration', 'ide'),
-                os.path.join(temp_directory, 'details', 'integration', 'os'),
-                os.path.join(temp_directory, 'details', 'integration', 'os', 'yocto'),
-                os.path.join(temp_directory, 'details', 'integration', 'renderers'),
-                os.path.join(temp_directory, 'details', 'libs'),
-                os.path.join(temp_directory, 'details', 'main-components'),
-                # Note:  details/main-components/display omitted intentionally,
+                project_dir,
+                intermediate_dir,
+                os.path.join(intermediate_dir, 'intro'),
+                os.path.join(intermediate_dir, 'details'),
+                os.path.join(intermediate_dir, 'details', 'common-widget-features'),
+                os.path.join(intermediate_dir, 'details', 'common-widget-features', 'layouts'),
+                os.path.join(intermediate_dir, 'details', 'common-widget-features', 'styles'),
+                os.path.join(intermediate_dir, 'details', 'debugging'),
+                os.path.join(intermediate_dir, 'details', 'integration'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'adding-lvgl-to-your-project'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'bindings'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'building'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'chip'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'driver'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'driver', 'display'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'driver', 'touchpad'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'framework'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'ide'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'os'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'os', 'yocto'),
+                os.path.join(intermediate_dir, 'details', 'integration', 'renderers'),
+                os.path.join(intermediate_dir, 'details', 'libs'),
+                os.path.join(intermediate_dir, 'details', 'main-modules'),
+                # Note:  details/main-modules/display omitted intentionally,
                 # since API links for those .RST files have been added manually.
-                os.path.join(temp_directory, 'details', 'other-components'),
-                os.path.join(temp_directory, 'details', 'widgets')
+                os.path.join(intermediate_dir, 'details', 'auxiliary-modules'),
+                os.path.join(intermediate_dir, 'details', 'widgets')
             )
 
         t2 = datetime.now()
-        print('Example/API processing run time:  ' + str(t2 - t1))
+        print('Example/API run time:  ' + str(t2 - t1))
 
     # ---------------------------------------------------------------------
     # Build PDF
@@ -631,26 +680,23 @@ def run():
         print("Building Latex output...")
         print("****************")
 
-        # Remove PDF link so PDF does not have a link to itself.
-        index_path = os.path.join(temp_directory, 'index.rst')
-
-        with open(index_path, 'rb') as f:
+        # If PDF link is present in top index.rst, remove it so PDF
+        # does not have a link to itself.
+        with open(top_index_file, 'rb') as f:
             index_data = f.read().decode('utf-8')
 
-        # Support both Windows and Linux platforms with `os.linesep`.
-        pdf_link_ref_str = 'PDF version: :download:`LVGL.pdf <LVGL.pdf>`' + os.linesep
         if pdf_link_ref_str in index_data:
             index_data = index_data.replace(pdf_link_ref_str, '')
 
-            with open(index_path, 'wb') as f:
+            with open(top_index_file, 'wb') as f:
                 f.write(index_data.encode('utf-8'))
 
-        # Silly workaround to include the more or less correct
-        # PDF download link in the PDF
-        # cmd("cp -f " + lang +"/latex/LVGL.pdf LVGL.pdf | true")
-        src = temp_directory
-        dst = output_path
+        src = intermediate_dir
+        dst = output_dir
         cpu = os.cpu_count()
+        # As of 22-Feb-2025, sadly the -D version=xxx is not working as documented.
+        # So the version strings applicable to Latex/PDF/man pages/texinfo
+        # formats are assembled by `conf.py`.
         cmd_line = f'sphinx-build -M latex "{src}" "{dst}" -j {cpu}'
         cmd(cmd_line)
 
@@ -659,21 +705,16 @@ def run():
         print("Building PDF...")
         print("****************")
         cmd_line = 'latexmk -pdf "LVGL.tex"'
-        cmd(cmd_line, latex_output_path, True)
+        cmd(cmd_line, latex_output_dir, False)
 
-        # Copy the result PDF to the main directory to make
-        # it available for the HTML build.
-        shutil.copyfile(pdf_src_file, pdf_dst_file)
-
-        # Add PDF link back in so HTML build will have it.
-        index_data = pdf_link_ref_str + index_data
-
-        with open(index_path, 'wb') as f:
-            f.write(index_data.encode('utf-8'))
+        # Move resulting PDF to its output directory.
+        if not os.path.exists(pdf_output_dir):
+            os.makedirs(pdf_output_dir)
 
+        shutil.move(pdf_src_file, pdf_dst_file)
         t2 = datetime.now()
         print('PDF           :  ' + pdf_dst_file)
-        print('Latex gen run time:  ' + str(t2 - t1))
+        print('Latex gen time:  ' + str(t2 - t1))
 
     # ---------------------------------------------------------------------
     # Build HTML
@@ -686,40 +727,53 @@ def run():
         print("Building HTML output...")
         print("****************")
 
+        # If PDF is present in build directory, copy it to
+        # intermediate directory for use by HTML build.
+        # (Sphinx copies it to its HTML output, so it ends
+        # up on the webserver where it can be downloaded).
+        if os.path.isfile(pdf_dst_file):
+            # Create _static/download/ directory if needed.
+            if not os.path.exists(pdf_intermediate_dst_dir):
+                os.makedirs(pdf_intermediate_dst_dir)
+
+            shutil.copyfile(pdf_dst_file, pdf_intermediate_dst_file)
+
+        # If PDF is present, ensure there is a link to it in the top
+        # index.rst so HTML build will have it.
+        # Support both Windows and Linux platforms with `os.linesep`.
+        if os.path.isfile(pdf_intermediate_dst_file):
+            with open(top_index_file, 'rb') as f:
+                index_data = f.read().decode('utf-8')
+
+            if pdf_link_ref_str not in index_data:
+                index_data = cfg_pdf_link_ref_block_str + index_data
+
+                with open(top_index_file, 'wb') as f:
+                    f.write(index_data.encode('utf-8'))
+
         # Note:  While it can be done (e.g. if one needs to set a stop point
         # in Sphinx code for development purposes), it is NOT a good idea to
         # run Sphinx from script as
         #   from sphinx.cmd.build import main as sphinx_build
         #   sphinx_args = [...]
         #   sphinx_build(sphinx_args)
-        # because it takes ~10X longer to run than `sphinx_build` executable.
-        # Literally > 3 hours.
+        # because it takes ~10X longer to run than `sphinx_build` executable,
+        # literally > 3 hours.
 
-        # '-E' option forces Sphinx to rebuild its environment so all docs are
-        # fully regenerated, even if not changed.
-        # Note:  Sphinx runs in ./docs/, but uses `temp_directory` for input.
-        if fresh_sphinx_env:
-            print("Regenerating all files...")
-            env_opt = '-E'
-        else:
-            print("Regenerating only updated files...")
-            env_opt = ''
-
-        ver = get_version(version_source_path)
-        src = html_src_path
-        dst = output_path
+        ver = lvgl_version(version_src_file)
+        src = intermediate_dir
+        dst = output_dir
         cpu = os.cpu_count()
+        # As of 22-Feb-2025, sadly the -D version=xxx is not working as documented.
+        # So the version strings applicable to Latex/PDF/man pages/texinfo
+        # formats are assembled by `conf.py`.  The -D option in the command
+        # line may go away if it does not, in fact, create some impact on
+        # the doc-gen process.
         cmd_line = f'sphinx-build -M html "{src}" "{dst}" -D version="{ver}" {env_opt} -j {cpu}'
         cmd(cmd_line)
         t2 = datetime.now()
         print('HTML gen time :  ' + str(t2 - t1))
 
-    # ---------------------------------------------------------------------
-    # Remove temporary `lv_conf.h` created for this build.
-    # Do this even when `lv_conf.h` was not generated in case a prior run got interrupted.
-    # ---------------------------------------------------------------------
-    config_builder.cleanup()
-
     # ---------------------------------------------------------------------
     # Indicate results.
     # ---------------------------------------------------------------------
@@ -728,8 +782,6 @@ def run():
     print('Done.')
 
 
-# -------------------------------------------------------------------------
-# Make module importable as well as run-able.
-# -------------------------------------------------------------------------
 if __name__ == '__main__':
-    run()
+    """Make module importable as well as run-able."""
+    run(sys.argv[1:])

docs/details/base-widget/index.rst

@@ -1,18 +0,0 @@
-.. _base_widget_overview:
-
-===========
-Base Widget
-===========
-
-The following details apply to all types of Widgets.
-
-.. toctree::
-    :maxdepth:  3
-
-    obj
-    coord
-    layer
-    styles/index
-    event
-    layouts/index
-    scroll

docs/index.rst

@@ -1,82 +0,0 @@
-.. raw:: html
-
-    <p style="text-align: right;">
-        <a class="reference external" href="https://lvgl.100ask.net/master/index.html">
-            [&#x04E2D;&#x02F42;] Chinese Translation
-        </a>
-    </p>
-
-.. _lvgl_landing_page:
-
-===========================================
-LVGL:  Light and Versatile Graphics Library
-===========================================
-
-Create beautiful UIs for any MCU, MPU and display type.
-*******************************************************
-
-.. raw:: html
-
-    <div style="margin-bottom:30px; margin-top:14px">
-    <img src="_static/img/gh-header.webp" alt="LVGL Documentation" style="width:100%">
-    </div>
-
-.. raw:: html
-
-    <div style="margin-bottom:48px">
-    <a href="intro/introduction.html"><img class="home-img" src="_static/img/home_1.png" alt="Get familiar with LVGL."></a>
-    <a href="intro/basics.html"><img class="home-img" src="_static/img/home_2.png" alt="Learn how LVGL works."></a>
-    <a href="intro/basics.html#going-deeper"><img class="home-img" src="_static/img/home_3.png" alt="Get your feet wet with LVGL."></a>
-    <a href="intro/add-lvgl-to-your-project/index.html"><img class="home-img" src="_static/img/home_4.png" alt="Learn how to add LVGL to your project for any platform, framework and display type."></a>
-    <a href="details/widgets/index.html"><img class="home-img" src="_static/img/home_5.png" alt="Learn to use LVGL Widgets with examples."></a>
-    <a href="CONTRIBUTING.html"><img class="home-img" src="_static/img/home_6.png" alt="Be part of LVGL's development."></a>
-    </div>
-
-
-Introduction
-------------
-
-.. toctree::
-    :maxdepth: 1
-
-    intro/introduction
-    intro/basics
-    intro/add-lvgl-to-your-project/index
-
-
-Details
--------
-
-.. toctree::
-    :maxdepth: 1
-
-    details/base-widget/index
-    details/widgets/index
-    details/main-components/index
-    details/other-components/index
-    examples
-    details/debugging/index
-    details/integration/index
-    details/libs/index
-    API/index
-
-
-Appendix
---------
-
-.. toctree::
-    :maxdepth: 1
-
-    CONTRIBUTING
-    CODING_STYLE
-    CHANGELOG
-    ROADMAP
-
-
-.. toctree::
-    :hidden:
-
-    intro/index
-    details/index
-
-

docs/make.bat

@@ -0,0 +1,58 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+setlocal ENABLEDELAYEDEXPANSION
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+if "%LVGL_DOC_BUILD_INTERMEDIATE_DIR%" == "" (
+	set SOURCEDIR=intermediate
+) else (
+	set SOURCEDIR=%LVGL_DOC_BUILD_INTERMEDIATE_DIR%
+)
+if "%SPHINXOPTS%" == "" (
+    rem python get_lvgl_version.py >_version_temp.txt
+    rem set /p VER=<_version_temp.txt
+    rem del _version_temp.txt
+    for /F %%v in ('python lvgl_version.py') do set VER=%%v
+    echo VERSION    [!VER!]
+	set SPHINXOPTS=-D version="!VER!" -j 4
+	set VER=
+)
+set BUILDDIR=build
+
+echo SOURCEDIR  [%SOURCEDIR%]
+echo BUILDDIR   [%BUILDDIR%]
+echo SPHINXOPTS [%SPHINXOPTS%]
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+echo %SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS% %2 %3 %4 %5 %6 %7 %8 %9
+%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS% %2 %3 %4 %5 %6 %7 %8 %9
+goto end
+
+:help
+%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS% %2 %3 %4 %5 %6 %7 %8 %9
+
+:end
+rem Clean up.
+popd
+set BUILDDIR=
+set SOURCEDIR=

docs/src/conf.py

@@ -19,11 +19,18 @@
 #
 import os
 import sys
-
-sys.path.insert(0, os.path.abspath('./_ext'))
-
+import re
 from sphinx.builders.html import StandaloneHTMLBuilder
 
+base_path = os.path.abspath(os.path.dirname(__file__))
+# Add path to import link_roles.py and lv_example.py
+sys.path.insert(0, os.path.abspath('./_ext'))
+# Add path to import lvgl_version.py.  Remember this is
+# running under `sphinx-build` environment, not `build.py`.
+sys.path.insert(0, base_path)
+from lvgl_version import lvgl_version #NoQA
+
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -73,8 +80,8 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'LVGL'
-copyright = '2024, LVGL Kft'
-author = 'LVGL community'
+copyright = '2024-2025, LVGL Kft'
+author = 'LVGL Community'
 
 
 # The version info for the project you're documenting, acts as replacement for
@@ -84,8 +91,13 @@ author = 'LVGL community'
 # The short X.Y version.
 # `version` is extracted from lv_version.h using a cross-platform compatible
 # Python function in build.py, and passed in on `sphinx-build` command line.
-
-version = ''
+#
+# 22-Feb-2025 Sadly, the `-D version=...` on the command line does not currently
+# actually work as documented.  Sphinx documentation says of `-D setting=value`
+# "Override a configuration value set in the conf.py file.".
+# So we have to do this to get the version string into various values below.
+version_src_path = os.path.join(base_path, 'lv_version.h')
+version = lvgl_version(version_src_path)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -190,8 +202,8 @@ html_js_files = [
     'js/include_html.js'
 ]
 
-html_favicon = 'favicon.png'
-html_logo = 'logo_lvgl.png'
+html_favicon = '_static/images/favicon.png'
+html_logo = '_static/images/logo_lvgl.png'
 
 # -- Options for HTMLHelp output ------------------------------------------
 
@@ -240,8 +252,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'LVGL.tex', 'LVGL Documentation ' + version,
-     'LVGL community', 'manual'),
+    (master_doc, 'LVGL.tex', 'LVGL v' + version,
+     author, 'manual'),
 ]
 
 
@@ -250,7 +262,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'lvgl', 'LVGL Documentation ' + version,
+    (master_doc, 'lvgl', 'LVGL v' + version,
      [author], 3)
 ]
 
@@ -261,7 +273,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'LVGL', 'LVGL Documentation ' + version,
+    (master_doc, 'LVGL', 'LVGL v' + version,
      author, 'Contributors of LVGL', 'One line description of project.',
      'Miscellaneous'),
 ]
@@ -296,8 +308,8 @@ repo_commit_hash = _git_commit_ref
 # The below generates .HTML page redirects for pages that have been moved.
 # Browsers are redirected via `<meta http-equiv="refresh" content="0; url=new_url">`.
 redirects = {
-    "get-started/index":                          "../intro/basics.html"                                            ,
-    "get-started/quick-overview":                 "../intro/basics.html"                                            ,
+    "get-started/index":                          "../intro/getting_started.html"                                   ,
+    "get-started/quick-overview":                 "../intro/getting_started.html"                                   ,
     "integration/bindings/api_json":              "../../details/integration/bindings/api_json.html"                ,
     "integration/bindings/cpp":                   "../../details/integration/bindings/cpp.html"                     ,
     "integration/bindings/index":                 "../../details/integration/bindings/index.html"                   ,
@@ -352,9 +364,9 @@ redirects = {
     "integration/os/yocto/lvgl_recipe":           "../../../details/integration/os/yocto/lvgl_recipe.html"          ,
     "integration/os/yocto/terms_and_variables":   "../../../details/integration/os/yocto/terms_and_variables.html"  ,
     "integration/os/zephyr":                      "../../details/integration/os/zephyr.html"                        ,
-    "layouts/flex":                               "../details/base-widget/layouts/flex.html"                        ,
-    "layouts/grid":                               "../details/base-widget/layouts/grid.html"                        ,
-    "layouts/index":                              "../details/base-widget/layouts/index.html"                       ,
+    "layouts/flex":                               "../details/common-widget-features/layouts/flex.html"             ,
+    "layouts/grid":                               "../details/common-widget-features/layouts/grid.html"             ,
+    "layouts/index":                              "../details/common-widget-features/layouts/index.html"            ,
     "libs/arduino_esp_littlefs":                  "../details/libs/arduino_esp_littlefs.html"                       ,
     "libs/arduino_sd":                            "../details/libs/arduino_sd.html"                                 ,
     "libs/barcode":                               "../details/libs/barcode.html"                                    ,
@@ -374,36 +386,36 @@ redirects = {
     "libs/svg":                                   "../details/libs/svg.html"                                        ,
     "libs/tiny_ttf":                              "../details/libs/tiny_ttf.html"                                   ,
     "libs/tjpgd":                                 "../details/libs/tjpgd.html"                                      ,
-    "others/file_explorer":                       "../details/other-components/file_explorer.html"                  ,
-    "others/font_manager":                        "../details/other-components/font_manager.html"                   ,
-    "others/fragment":                            "../details/other-components/fragment.html"                       ,
-    "others/gridnav":                             "../details/other-components/gridnav.html"                        ,
-    "others/ime_pinyin":                          "../details/other-components/ime_pinyin.html"                     ,
-    "others/imgfont":                             "../details/other-components/imgfont.html"                        ,
-    "others/index":                               "../details/other-components/index.html"                          ,
-    "others/monkey":                              "../details/other-components/monkey.html"                         ,
-    "others/obj_id":                              "../details/other-components/obj_id.html"                         ,
-    "others/obj_property":                        "../details/other-components/obj_property.html"                   ,
-    "others/observer":                            "../details/other-components/observer.html"                       ,
-    "others/snapshot":                            "../details/other-components/snapshot.html"                       ,
-    "overview/animations":                        "../details/main-components/animation.html"                       ,
-    "overview/color":                             "../details/main-components/color.html"                           ,
-    "overview/coord":                             "../details/base-widget/coord.html"                               ,
+    "others/file_explorer":                       "../details/auxiliary-modules/file_explorer.html"                 ,
+    "others/font_manager":                        "../details/auxiliary-modules/font_manager.html"                  ,
+    "others/fragment":                            "../details/auxiliary-modules/fragment.html"                      ,
+    "others/gridnav":                             "../details/auxiliary-modules/gridnav.html"                       ,
+    "others/ime_pinyin":                          "../details/auxiliary-modules/ime_pinyin.html"                    ,
+    "others/imgfont":                             "../details/auxiliary-modules/imgfont.html"                       ,
+    "others/index":                               "../details/auxiliary-modules/index.html"                         ,
+    "others/monkey":                              "../details/auxiliary-modules/monkey.html"                        ,
+    "others/obj_id":                              "../details/auxiliary-modules/obj_id.html"                        ,
+    "others/obj_property":                        "../details/auxiliary-modules/obj_property.html"                  ,
+    "others/observer":                            "../details/auxiliary-modules/observer.html"                      ,
+    "others/snapshot":                            "../details/auxiliary-modules/snapshot.html"                      ,
+    "overview/animations":                        "../details/main-modules/animation.html"                          ,
+    "overview/color":                             "../details/main-modules/color.html"                              ,
+    "overview/coord":                             "../details/common-widget-features/coord.html"                    ,
     "overview/debugging/gdb_plugin":              "../../details/debugging/gdb_plugin.html"                         ,
     "overview/debugging/index":                   "../../details/debugging/index.html"                              ,
     "overview/debugging/log":                     "../../details/debugging/log.html"                                ,
     "overview/debugging/profiler":                "../../details/debugging/profiler.html"                           ,
     "overview/debugging/vg_lite_tvg":             "../../details/debugging/vg_lite_tvg.html"                        ,
-    "overview/display":                           "../details/main-components/display/index.html"                   ,
-    "overview/event":                             "../details/base-widget/event.html"                               ,
-    "overview/font":                              "../details/main-components/font.html"                            ,
-    "overview/fs":                                "../details/main-components/fs.html"                              ,
-    "overview/image":                             "../details/main-components/image.html"                           ,
-    "overview/indev":                             "../details/main-components/indev.html"                           ,
-    "overview/index":                             "../details/main-components/index.html"                           ,
-    "overview/layer":                             "../details/base-widget/layer.html"                               ,
+    "overview/display":                           "../details/main-modules/display/index.html"                      ,
+    "overview/event":                             "../details/common-widget-features/event.html"                    ,
+    "overview/font":                              "../details/main-modules/font.html"                               ,
+    "overview/fs":                                "../details/main-modules/fs.html"                                 ,
+    "overview/image":                             "../details/main-modules/image.html"                              ,
+    "overview/indev":                             "../details/main-modules/indev.html"                              ,
+    "overview/index":                             "../details/main-modules/index.html"                              ,
+    "overview/layer":                             "../details/common-widget-features/layer.html"                    ,
     "overview/new_widget":                        "../details/widgets/new_widget.html"                              ,
-    "overview/obj":                               "../details/base-widget/obj.html"                                 ,
+    "overview/obj":                               "../details/common-widget-features/obj.html"                      ,
     "overview/renderers/arm2d":                   "../../details/integration/renderers/arm2d.html"                  ,
     "overview/renderers/index":                   "../../details/integration/renderers/index.html"                  ,
     "overview/renderers/nema_gfx":                "../../details/integration/renderers/nema_gfx.html"               ,
@@ -413,13 +425,13 @@ redirects = {
     "overview/renderers/sw":                      "../../details/integration/renderers/sw.html"                     ,
     "overview/renderers/vg_lite":                 "../../details/integration/renderers/vg_lite.html"                ,
     "overview/renderers/vglite":                  "../../details/integration/renderers/nxp_vglite_gpu.html"         ,
-    "overview/scroll":                            "../details/base-widget/scroll.html"                              ,
-    "overview/style":                             "../details/base-widget/styles/style.html"                        ,
-    "overview/style-props":                       "../details/base-widget/styles/style-properties.html"             ,
-    "overview/timer":                             "../details/main-components/timer.html"                           ,
-    "porting/display":                            "../details/main-components/display.html"                         ,
-    "porting/draw":                               "../details/main-components/draw.html"                            ,
-    "porting/indev":                              "../details/main-components/indev.html"                           ,
+    "overview/scroll":                            "../details/common-widget-features/scroll.html"                   ,
+    "overview/style":                             "../details/common-widget-features/styles/style.html"             ,
+    "overview/style-props":                       "../details/common-widget-features/styles/style-properties.html"  ,
+    "overview/timer":                             "../details/main-modules/timer.html"                              ,
+    "porting/display":                            "../details/main-modules/display.html"                            ,
+    "porting/draw":                               "../details/main-modules/draw.html"                               ,
+    "porting/indev":                              "../details/main-modules/indev.html"                              ,
     "porting/index":                              "../intro/add-lvgl-to-your-project/index.html"                    ,
     "porting/os":                                 "../intro/add-lvgl-to-your-project/threading.html"                ,
     "porting/project":                            "../intro/add-lvgl-to-your-project/connecting_lvgl.html"          ,
@@ -447,7 +459,7 @@ redirects = {
     "widgets/lottie":                             "../details/widgets/lottie.html"                                  ,
     "widgets/menu":                               "../details/widgets/menu.html"                                    ,
     "widgets/msgbox":                             "../details/widgets/msgbox.html"                                  ,
-    "widgets/obj":                                "../details/base-widget/obj.html"                                 ,
+    "widgets/obj":                                "../details/widgets/base_widget.html"                             ,
     "widgets/roller":                             "../details/widgets/roller.html"                                  ,
     "widgets/scale":                              "../details/widgets/scale.html"                                   ,
     "widgets/slider":                             "../details/widgets/slider.html"                                  ,

docs/src/contributing/dco.rst

@@ -0,0 +1,70 @@
+.. _contributing_dco:
+
+=======================================
+Developer Certification of Origin (DCO)
+=======================================
+
+Overview
+********
+
+To ensure all licensing criteria are met for every repository of the
+LVGL project, we apply a process called DCO (Developer's Certificate of
+Origin).
+
+The text of DCO can be read here: https://developercertificate.org/.
+
+By contributing to any repositories of the LVGL project you agree that
+your contribution complies with the DCO.
+
+If your contribution fulfills the requirements of the DCO, no further
+action is needed. If you are unsure feel free to ask us in a comment,
+e.g. in your submitted :ref:`Pull Request <contributing_pull_requests>`.
+
+
+
+Accepted Licenses and Copyright Notices
+***************************************
+
+To make the DCO easier to digest, here are some practical guides about
+specific cases:
+
+Your own work
+-------------
+
+The simplest case is when the contribution is solely your own work. In
+this case you can just send a Pull Request without worrying about any
+licensing issues.
+
+Using code from an online source
+--------------------------------
+
+If the code you would like to add is based on an article, post or
+comment on a website (e.g. StackOverflow) the license and/or rules of
+that site should be followed.
+
+For example in case of StackOverflow a notice like this can be used:
+
+.. code-block::
+
+   /* The original version of this code-snippet was published on StackOverflow.
+    * Post: http://stackoverflow.com/questions/12345
+    * Author: http://stackoverflow.com/users/12345/username
+    * The following parts of the snippet were changed:
+    * - Check this or that
+    * - Optimize performance here and there
+    */
+    ... code snippet here ...
+
+Using MIT-licensed code
+-----------------------
+
+As LVGL is MIT licensed, other MIT licensed code can be integrated
+without issues. The MIT license requires a copyright notice be added to
+the derived work. Any derivative work based on MIT licensed code must
+copy the original work's license file or text.
+
+Use GPL-licensed code
+---------------------
+
+The GPL license is not compatible with the MIT license. Therefore, LVGL
+cannot accept GPL licensed code.

docs/src/contributing/index.rst

@@ -0,0 +1,14 @@
+.. _contributing:
+
+============
+Contributing
+============
+
+.. toctree::
+    :maxdepth: 1
+
+    introduction
+    ways_to_contribute
+    pull_requests
+    dco
+    coding_style

docs/src/contributing/introduction.rst

@@ -0,0 +1,18 @@
+.. _contributing_intro:
+
+============
+Introduction
+============
+
+Join LVGL's community and leave your footprint in the library!
+
+There are a lot of ways to contribute to LVGL even if you are new to the
+library or even new to programming.
+
+It might be scary to make the first step but you have nothing to be
+afraid of. A friendly and helpful community is waiting for you. Get to
+know like-minded people and make something great together.
+
+So let's find which contribution option fits you the best and helps you
+join the development of LVGL!
+

docs/src/contributing/pull_requests.rst

@@ -0,0 +1,129 @@
+.. _contributing_pull_requests:
+
+=============
+Pull Requests
+=============
+
+Merging new code into the ``lvgl/lvgl`` and other
+repositories happens via *Pull Requests* (PR for short). A PR is a
+notification like "Hey, I made some updates to your project. Here are
+the changes, you can add them if you want." To do this you need a copy
+(called fork) of the original project under your account, make some
+changes there, and notify the original repository about your updates.
+You can see what it looks like on GitHub for LVGL here:
+https://github.com/lvgl/lvgl/pulls.
+
+To add your changes you can edit files online on GitHub and send a new
+Pull request from there (recommended for small changes) or add the
+updates in your favorite editor/IDE and use ``git`` to publish the changes
+(recommended for more complex updates).
+
+
+
+From GitHub
+***********
+
+1. Navigate to the file you want to edit.
+2. Click the Edit button in the top right-hand corner.
+3. Add your changes to the file.
+4. Add a commit message at the bottom of the page.
+5. Click the *Propose changes* button.
+
+
+
+From Your Local Workstation
+***************************
+
+These instructions describe the main ``lvgl`` repository but it works the
+same way any remote Git repository.
+
+1. Fork the `lvgl repository <https://github.com/lvgl/lvgl>`__. To do this click the
+   "Fork" button in the top right corner. It will "copy" the ``lvgl``
+   repository to your GitHub account (``https://github.com/<YOUR_NAME>?tab=repositories``)
+2. Clone your forked repository.
+3. Add your changes. You can create a *feature branch* from the ``master`` branch for the updates: ``git checkout -b <new-feature-branch-name>``
+4. Commit and push your changes to your forked ``lvgl`` repository.
+5. Create a PR on GitHub from the page of your forked ``lvgl`` repository (``https://github.com/<YOUR_NAME>/lvgl``) by
+   clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes.
+6. Set the base branch where you want to merge your update. In the ``lvgl`` repo both fixes
+   and new features should be directed to the ``master`` branch.
+7. Describe what is in the update.  Example code is welcome if applicable.
+8. If you need to make more changes, just update your forked ``lvgl`` repo with new commits.
+   They will automatically appear in the PR.
+
+
+
+.. _contributing_commit_message_format:
+
+Commit Message Format
+*********************
+
+The commit messages format is inspired by `Angular Commit
+Format <https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit>`__.
+
+The following structure should be used:
+
+.. code-block:: text
+
+    <type>(<scope>): <subject>
+                <--- blank line
+    <body>
+                <--- blank line
+    <footer>
+
+Possible ``<type>``\ s:
+
+- ``fix`` bugfix in LVGL source code
+- ``feat`` new feature
+- ``arch`` architectural changes
+- ``perf`` changes that affect performance
+- ``example`` anything related to examples (including fixes and new examples)
+- ``docs`` anything related to documentation (including fixes, formatting, and new pages)
+- ``test`` anything related to tests (new and updated tests or CI actions)
+- ``chore`` any minor formatting or style changes that would make the changelog noisy
+
+``<scope>`` is the name of the module, file, or subsystem affected by the
+commit. It's usually one word and can be chosen freely. For example
+``img``, ``layout``, ``txt``, ``anim``. The scope can be omitted.
+
+``<subject>`` contains a short description of the change following these guidelines:
+
+- use the imperative mood:  e.g. present tense "change", not "changed" nor "changes";
+- don't capitalize the first letter;
+- no period (``.``) at the end;
+- max 90 characters.
+
+``<body>`` optional and can be used to describe the details of this
+change.
+
+``<footer>`` shall contain
+
+- the words "BREAKING CHANGE" if the changes break the API
+- reference to the GitHub issue or Pull Request if applicable.
+  (See `Linking a pull rquest to an issue <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue>`__
+  for details.)
+
+Some examples:
+
+.. code-block:: text
+
+    fix(image): update size when a new source is set
+
+.. code-block:: text
+
+    fix(bar): fix memory leak
+
+    The animations weren't deleted in the destructor.
+
+    Fixes: #1234
+
+.. code-block:: text
+
+    feat: add span widget
+
+    The span widget allows mixing different font sizes, colors and styles.
+    It's similar to HTML <span>
+
+.. code-block:: text
+
+    docs(porting): fix typo

docs/src/contributing/ways_to_contribute.rst

@@ -0,0 +1,23 @@
+.. _contributing_ways:
+
+==================
+Ways to Contribute
+==================
+
+- **Spread the Word**: Share your LVGL experience with friends or on social media to boost its visibility.
+- **Star LVGL**   Give us a star on `GitHub <https://github.com/lvgl/lvgl>`__! It helps a lot to make LVGL more appealing for newcomers.
+- **Report a Bug**: Open a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__ if something is not working.
+- **Join Our** `Forum <https://forum.lvgl.io/>`__ : Meet fellow developers and discuss questions.
+- **Tell Us Your Ideas**: If you feel something is missing from LVGL, we would love to hear about it in a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__
+- **Develop Features**: Help to design or develop a feature. See below.
+
+Mid- and large-scale issues are discussed in `Feature Planning <https://github.com/lvgl/lvgl/issues/new?assignees=&labels=&projects=&template=feat-planning.yml>`__ issues.
+
+An issue can be developed when all the questions in the issue template are answered and there are no objection from any core member.
+
+We are using GitHub labels to show the state and attributes of the issues and Pull requests.
+If you are looking for contribution opportunities you can `Filter for these labels <https://github.com/lvgl/lvgl/labels>`__ :
+
+- ``Simple``: Good choice to get started with an LVGL contribution
+- ``PR needed``: We investigated the issue but it still needs to be implemented
+- ``Review needed``: A Pull request is opened and it needs review/testing

docs/src/details/auxiliary-modules/index.rst

@@ -1,8 +1,8 @@
-.. _others:
+.. _auxiliary_modules:
 
-================
-Other Components
-================
+=================
+Auxiliary Modules
+=================
 
 .. toctree::
     :maxdepth: 1

docs/src/details/auxiliary-modules/xml/components.rst

@@ -5,7 +5,7 @@ Components
 ==========
 
 Overview
---------
+********
 
 ``<component>`` can have ``<consts>``, ``<api>``, ``<styles>``, and ``<view>`` tags inside.
 
@@ -14,8 +14,10 @@ Unlike widgets (which are always compiled into the application), components can
 1. Be loaded at runtime from XML.
 2. Be exported to C code.
 
-Usage from exported code
-------------------------
+
+
+Usage from Exported Code
+************************
 
 From each component XML file, a C and H file is exported with a single function inside:
 
@@ -30,11 +32,13 @@ If the user needs to access or modify values dynamically, it is recommended to u
 
 The user can also call these ``_create_`` functions at any time from the application code.
 
+
+
 Usage from XML
---------------
+**************
 
 Registration
-^^^^^^^^^^^^
+------------
 
 Once a component is created (e.g., ``my_button``), it can be registered by calling either:
 
@@ -47,7 +51,7 @@ This is required to make LVGL recognize the component by name.
 When loaded from a file, the file name is used as the component name.
 
 Instantiation
-^^^^^^^^^^^^^
+-------------
 
 After registration, a new instance of any registered component can be created with:
 
@@ -72,8 +76,10 @@ The last parameter can be ``NULL`` or an attribute list, like this:
 
     lv_obj_t * btn1 = lv_xml_create(lv_screen_active(), "my_button", my_button_attrs);
 
+
+
 Parameters
-----------
+**********
 
 The properties of child elements can be adjusted, such as:
 
@@ -127,10 +133,14 @@ The following example demonstrates parameter passing and the use of the
     };
     lv_xml_create(lv_screen_active(), "red_button", attrs);
 
+
+
 Example
 *******
 
-.. include:: ../../examples/others/xml/index.rst
+.. include:: ../../../examples/others/xml/index.rst
+
+
 
 API
 ***