docs(misc): pre-re-org wrap-up... (#7804)

Co-authored-by: Felipe Neves <ryukokki.felipe@gmail.com>

.gitignore

@@ -5,19 +5,8 @@
 **/*.gcda
 **/*.gcno
 tags
-docs/api_doc
 scripts/cppcheck_res.txt
 scripts/built_in_font/lv_font_*
-docs/doxygen_html
-docs/xml
-docs/examples.md
-docs/tmp/
-docs/output/
-docs/_static/built_lv_examples
-docs/LVGL.pdf
-docs/env
-docs/examples.rst
-docs/API/
 __pycache__
 /emscripten_builder
 test_screenshot_error.h

docs/.gitignore

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

docs/README.md

@@ -3,15 +3,17 @@
 
 ## Building
 
-Building the documentation is pretty easy to do but it does have some requirements that have to be filled prior to building them.
-
-Here are the requirements:
+Building the documentation is easy.  Here are the requirements:
 
 * Doxygen
 * Python >= 3.10
 * C compiler (gcc, msvc, clang, etc...)
 
-There are also some Python specific libraries that need to be installed. You can either install these individually or you can use pip to read the requirements file to install everything that is needed for Python.
+Once Python is installed
+
+    pip install -r requirements.txt
+
+will install all the prerequisite packages:
 
 * Sphinx
 * breathe
@@ -32,26 +34,34 @@ There are also some Python specific libraries that need to be installed. You can
 * sphinx-reredirects
 * dirsync
 
-To install using the `requirements.txt` file use the following command:
+Now you are ready to build the documentation:
 
-    pip install -r requirements.txt
+    python build.py html
 
-Once you have all of the requirements installed you are ready to build the documentation.  Use the following command:
+or if you are on a Unix like OS:
 
-    python build.py skip_latex clean
+    python3 build.py html
 
-You may have to use the following command if you are on a Unix like OS
+Intermediate files are prepared in `./docs/intermediate/` and the final documentation will appear in `./docs/build/html/`.
 
-    python3 build.py skip_latex clean
+If the list of document source files has changed (names or paths):
 
-The documentation will be output into `./out_html/` in the root directory for LVGL.
+    python build.py clean html
+
+Will remove the old intermediate and build files and regenerate new ones matching the new structure.
+
+To see a list of options available:
+
+    python build.py
+
+Read the docstring for `build.py` for detailed documentation on each option.
 
 
 ## For Developers
 
-The most important thing that has to be done when contributing to LVGL is ***EVERYTHING MUST BE DOCUMENTED***.
+One of our firm policies is ***EVERYTHING MUST BE DOCUMENTED***.
 
-The below are some rules to follow when updating any of the `.rst` files located in the `./docs/` directory and any of it's subdirectories.
+The below are some rules to follow when updating any of the `.rst` files located in the `./docs/src/` directory tree.
 
 
 ### What to Name Your `.rst` File

docs/build.py

@@ -725,10 +725,6 @@ def run():
     # ---------------------------------------------------------------------
     t_end = datetime.now()
     print('Total run time:  ' + str(t_end - t0))
-    print()
-    print('Note:  warnings about `/details/index.rst` and `/intro/index.rst`')
-    print('       "not being in any toctree" are expected and intentional.')
-    print()
     print('Done.')
 
 

docs/conf.py

@@ -132,7 +132,7 @@ html_theme_options = {
     # Toc options
     'sticky_navigation': True,
     'navigation_depth': 4,
-    'includehidden': True,
+    'includehidden': False,
     'titles_only': False,
 
     'collapse_navigation': False,
@@ -251,7 +251,7 @@ latex_documents = [
 # (source start file, name, description, authors, manual section).
 man_pages = [
     (master_doc, 'lvgl', 'LVGL Documentation ' + version,
-     [author], 1)
+     [author], 3)
 ]
 
 

docs/details/main-components/display/refreshing.rst

@@ -10,10 +10,7 @@ Default Refresh Behavior
 Normally the dirty (a.k.a invalid) areas are checked and redrawn in
 every :c:macro:`LV_DEF_REFR_PERIOD` milliseconds (set in ``lv_conf.h``).
 This happens as a result of a refresh :ref:`timer` created that gets created when
-the display is created
-executed
-at that
-interval
+the display is created, and is executed at that interval.
 
 
 
@@ -42,10 +39,10 @@ You can do this in the following way:
    lv_display_refr_timer(NULL);
 
 If you have multiple displays call :cpp:expr:`lv_display_set_default(display1)` to
-select the display to refresh before :cpp:expr:`_lv_display_refr_timer(NULL)`.
+select the display to refresh before :cpp:expr:`lv_display_refr_timer(NULL)`.
 
 
-.. note:: :cpp:func:`lv_timer_handler` and :cpp:func:`_lv_display_refr_timer` must not run at the same time.
+.. note:: :cpp:func:`lv_timer_handler` and :cpp:func:`lv_display_refr_timer` must not run at the same time.
 
 
 If the performance monitor is enabled, the value of :c:macro:`LV_DEF_REFR_PERIOD` needs to be set to be

docs/index.rst

@@ -73,3 +73,10 @@ Appendix
     ROADMAP
 
 
+.. toctree::
+    :hidden:
+
+    intro/index
+    details/index
+
+

src/misc/lv_event.h

@@ -109,8 +109,8 @@ typedef enum {
     LV_EVENT_RENDER_READY,        /**< Sent after rendering has been completed (before calling flush callback) */
     LV_EVENT_FLUSH_START,         /**< Sent before flush callback is called. */
     LV_EVENT_FLUSH_FINISH,        /**< Sent after flush callback call has returned. */
-    LV_EVENT_FLUSH_WAIT_START,    /**<  */
-    LV_EVENT_FLUSH_WAIT_FINISH,   /**<  */
+    LV_EVENT_FLUSH_WAIT_START,    /**< Sent before flush wait callback is called. */
+    LV_EVENT_FLUSH_WAIT_FINISH,   /**< Sent after flush wait callback call has returned. */
 
     LV_EVENT_VSYNC,