feat(docs): new docs-build paradigm... (#7597)

.github/workflows/compile_docs.yml

@@ -64,9 +64,9 @@ jobs:
       - name: Build examples (with cache)
         run: scripts/build_html_examples.sh
       - name: Build docs
-        run: docs/build.py skip_latex
+        run: docs/build.py html
       - name: Remove .doctrees
-        run: rm -rf out_html/.doctrees
+        run: rm -rf docs/output/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: out_html  # The folder the action should deploy.
+          folder: docs/output/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: out_html  # The folder the action should deploy.
+          folder: docs/output/html  # The folder the action should deploy.
           target-folder: master
           git-config-name: lvgl-bot
           git-config-email: lvgl-bot@users.noreply.github.com

.gitignore

@@ -11,13 +11,13 @@ scripts/built_in_font/lv_font_*
 docs/doxygen_html
 docs/xml
 docs/examples.md
-docs/out_latex
+docs/tmp/
+docs/output/
 docs/_static/built_lv_examples
 docs/LVGL.pdf
 docs/env
-/docs/examples.rst
-/docs/API/
-out_html
+docs/examples.rst
+docs/API/
 __pycache__
 /emscripten_builder
 test_screenshot_error.h

docs/Doxyfile

@@ -733,14 +733,14 @@ QUIET                  = YES
 # Tip: Turn warnings on while writing the documentation.
 # The default value is: YES.
 
-WARNINGS               = NO
+WARNINGS               = YES
 
 # If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
 # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_UNDOCUMENTED   = YES
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters
@@ -748,7 +748,7 @@ WARN_IF_UNDOCUMENTED   = NO
 # markup commands wrongly.
 # The default value is: YES.
 
-WARN_IF_DOC_ERROR      = NO
+WARN_IF_DOC_ERROR      = YES
 
 # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
 # are documented, but have no documentation for their parameters or return
@@ -778,7 +778,7 @@ WARN_FORMAT            = "WARNING: $file:$line: $text"
 # messages should be written. If left blank the output is written to standard
 # error (stderr).
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = doxygen_warnings.txt
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
@@ -790,7 +790,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = *#*#SRC#*#*
+INPUT                  = <<SRC>>
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -850,8 +850,15 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */libs/thorvg/rapidjson/* \
-                         */libs/thorvg/tvg*
+EXCLUDE_PATTERNS       = */libs/barcode/code*     \
+                         */libs/freetype/ft*      \
+                         */libs/gif/gif*          \
+                         */libs/lodepng/lode*     \
+                         */libs/qrcode/qr*        \
+                         */libs/thorvg/*          \
+                         */libs/tiny_ttf/stb*     \
+                         */libs/tjpgd/tjp*        \
+                         */others/vg_lite_tvg/vg*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1203,7 +1210,7 @@ HTML_COLORSTYLE_GAMMA  = 80
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_TIMESTAMP         = NO
+# HTML_TIMESTAMP         = NO   # Obsolete
 
 # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
 # documentation will contain sections that can be hidden and shown after the
@@ -1788,7 +1795,7 @@ LATEX_BIB_STYLE        = plain
 # The default value is: NO.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_TIMESTAMP        = NO
+# LATEX_TIMESTAMP        = NO  # Obsolete
 
 #---------------------------------------------------------------------------
 # Configuration options related to the RTF output
@@ -2061,7 +2068,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DOXYGEN LV_CONF_PATH="#*#*LV_CONF_PATH*#*#"
+PREDEFINED             = DOXYGEN LV_CONF_PATH="<<LV_CONF_PATH>>"
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

docs/conf.py

@@ -33,6 +33,9 @@ from sphinx.builders.html import StandaloneHTMLBuilder
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+#
+# As of 6-Jan-2025, `link_roles` is being commented out because it is being
+# replaced by a manually-installed translation link in ./docs/index.rst.
 extensions = [
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
@@ -43,7 +46,7 @@ extensions = [
     'lv_example',
     'sphinx_design',
     'sphinx_rtd_dark_mode',
-    'link_roles',
+    # 'link_roles',
     'sphinxcontrib.mermaid',
     'sphinx_reredirects'
 ]

docs/details/index.rst

@@ -1,8 +1,8 @@
 .. _reference:
 
-=========
-Reference
-=========
+=======
+Details
+=======
 
 .. toctree::
     :maxdepth: 2

docs/details/main-components/animation.rst

@@ -192,7 +192,7 @@ you can set it like this:
 
 
 
-.. _animation_direction
+.. _animation_direction:
 
 Animating in Both Directions
 ****************************

docs/index.rst

@@ -1,6 +1,17 @@
+.. 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.
 *******************************************************
 

examples/widgets/canvas/index.rst

@@ -56,10 +56,10 @@ Draw Fancy Letter Effects
 -------------------------
 
 .. lv_example:: widgets/canvas/lv_example_canvas_9
-:language: c
+  :language: c
 
 Draw Fancy Letter Effects 2
 ---------------------------
 
 .. lv_example:: widgets/canvas/lv_example_canvas_10
-:language: c
+  :language: c