diff --git a/.gitignore b/.gitignore index cbf7580230..fe8e4a8650 100644 --- a/.gitignore +++ b/.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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..30fa502e4d --- /dev/null +++ b/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 diff --git a/docs/README.md b/docs/README.md index f895f15e42..230a689d78 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/build.py b/docs/build.py index 89501c2427..d82ef16c9a 100755 --- a/docs/build.py +++ b/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.') diff --git a/docs/conf.py b/docs/conf.py index d314ff98f3..fc710e4185 100755 --- a/docs/conf.py +++ b/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) ] diff --git a/docs/details/main-components/display/refreshing.rst b/docs/details/main-components/display/refreshing.rst index c7d56f4ede..b32798080d 100644 --- a/docs/details/main-components/display/refreshing.rst +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 8e1454935a..e9f966d852 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -73,3 +73,10 @@ Appendix ROADMAP +.. toctree:: + :hidden: + + intro/index + details/index + + diff --git a/src/misc/lv_event.h b/src/misc/lv_event.h index 21e7b646ef..11c6aecc85 100644 --- a/src/misc/lv_event.h +++ b/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,