1# Documentation
2
3
4## Building
5
6Building the documentation is pretty easy to do but it does have some requirements that have to be filled prior to building them.
7
8Here are the requirements:
9
10* Doxygen
11* Python >= 3.10
12* C compiler (gcc, msvc, clang, etc...)
13
14There 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.
15
16* Sphinx
17* breathe
18* imagesize
19* importlib-metadata
20* sphinx-rtd-theme
21* sphinx-sitemap
22* sphinxcontrib-applehelp
23* sphinxcontrib-devhelp
24* sphinxcontrib-htmlhelp
25* sphinxcontrib-jsmath
26* sphinxcontrib-qthelp
27* sphinxcontrib-serializinghtml
28* sphinxcontrib-mermaid==0.9.2
29* sphinx-design
30* sphinx-rtd-dark-mode
31* typing-extensions
32* sphinx-reredirects
33* dirsync
34
35To install using the `requirements.txt` file use the following command:
36
37    pip install -r requirements.txt
38
39Once you have all of the requirements installed you are ready to build the documentation.  Use the following command:
40
41    python build.py skip_latex clean
42
43You may have to use the following command if you are on a Unix like OS
44
45    python3 build.py skip_latex clean
46
47The documentation will be output into `./out_html/` in the root directory for LVGL.
48
49
50## For Developers
51
52The most important thing that has to be done when contributing to LVGL is ***EVERYTHING MUST BE DOCUMENTED***.
53
54The below are some rules to follow when updating any of the `.rst` files located in the `./docs/` directory and any of it's subdirectories.
55
56
57### What to Name Your `.rst` File
58
59The documentation-generation logic uses the stem of the file name (i.e. "event" from file name "event.rst") and compares this with code-element names found by Doxygen.  If a match is found, then it appends hyperlinks to the API pages that contain those code elements (names of macros, enum/struct/union types, variables, namespaces, typedefs and functions).
60
61If this is appropriate for the .RST file you are creating, ensure the stem of the file name matches the beginning part of the code-element name you want it to be associated with.
62
63If this is *not* appropriate for the .RST file you are creating, ensure the stem of the file name DOES NOT match any code-element names found in the LVGL header files under the ./src/ directory.
64
65In alignment with the above, use a file name stem that is appropriate to the topic being covered.
66
67
68### Text Format
69
70While with `.md` files, it is important to allow paragraphs to flow off to the right with one long line so that when they are formatted as `.html` files, the paragraphs will word-wrap with the width of the browser, this is not true with reStructuredText (`.rst` files).  [Sphinx](https://www.sphinx-doc.org/en/master/) and its underlying [docutils parsing engine](https://docutils.sourceforge.io/docs/) conveniently combine grouped text into a proper paragraph with that word-wrapping behavior.  This allows the source text documents to be nicely word-wrapped so that they are more readable in text- and code-editors that do not have wide editing windows.  So please wrap the text around column 86 or narrower.  Wrapping at *exactly* column 86 is not important, but readability and ease of editing is.
71
72
73### index.rst Files
74
75If you create a new directory you MUST have an `index.rst` file in that directory and that index file needs to be pointed to in the `index.rst` file that is located in the parent directory.
76
77Let's take a look at the `index.rst` file that is located in the `docs/layouts` directory.
78
79```
80.. _layouts:
81
82=======
83Layouts
84=======
85
86
87.. toctree::
88    :maxdepth: 2
89
90    flex
91    grid
92```
93
94
95The below explains the parts of this file.
96
97```
98.. _layouts:      <=== Creates an explicit link target
99                  <=== Empty line -- important!
100=======
101Layouts           <=== Heading seen in documentation
102=======
103
104
105.. toctree::      <=== Table of contents
106    :maxdepth: 2  <=== Internal use and needs to always be set this way
107
108    flex          <=== .rst files located in directory with index.rst
109    grid
110```
111
112The first line is for the purposes of providing a uniquely-named **link target** that can be referenced elsewhere in the documentation.
113
114    .. _{LINK NAME}:
115
116Note that `{LINK NAME}`:
117
118- **must** be preceded by a single underscore, and
119- **must** be followed by at least one blank line for the doc-generation logic to process it correctly.
120
121Replace `{LINK NAME}` with a link name that is unique among all documents under the `./docs/` directory.  It can have multiple words if needed to make it unique or when otherwise appropriate for clarity.  If multiple words are used, they can be separated with single spaces, hyphens or underscores.  Whatever you use, the `{LINK NAME}` string used to reference it must be identical.  `{LINK NAME}` strings are not case sensitive.
122
123That unique name is then used to provide a link reference elsewhere in the documentation using one of two formats.
124
125
126
127##### When "link text" should be a title or section heading from the target document:
128
129```reStructuredText
130:ref:`{LINK NAME}`
131```
132
133This in-line markup (interpreted text using the Sphinx-defined custom `:ref:` role) is then replaced with a hyperlink whose "link text" is the name of the section heading just below the **link target**.  For this reason, when using this syntax, `{LINK NAME}` must reference **link target**s that are just above a title or section heading.
134
135
136
137##### When "link text" should be something else:
138
139```reStructuredText
140:ref:`other link text <{LINK NAME}>`
141```
142
143This latter syntax enables you to put a **link target** anywhere in an .RST file (not just above a heading) and link to it using this syntax.
144
145Note:  This latter syntax was either added or fixed in Sphinx recently.  It did not work in Sphinx 7.3.7.
146
147
148
149
150### Section Headings
151
152[Section headings](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text.  Example:
153
154```
155=================
156This Is a Heading
157=================
158```
159
160reStructuredText does not impose any particular heading levels assigned to certain characters since the structure is determined from the succession of headings.  So if you are modifying an existing .RST file, please follow the pattern already in use.
161
162If you are creating a new .RST file, use this convention:
163
164```
165=====
166Title
167=====
168
169Chapter
170*******
171
172Section
173-------
174
175Sub Section
176~~~~~~~~~~~
177
178Sub Sub Section
179^^^^^^^^^^^^^^^
180
181Sub Sub Sub Section
182'''''''''''''''''''
183```
184
185Note that the "underlining" can be longer than the heading title, but if it is shorter, the documentation-generation logic will fail with an error.
186
187For improved readability in the .RST file, place at least 2 blank lines above section headings.
188
189
190### Code Blocks
191
192* Do not use tab characters in code blocks.
193* Each indentation level use 4 spaces.
194* Include at least 1 empty line after a code block.
195* There must be one empty line between the code block directive and the code.
196* `.. code-block::` is the only directive that should be used.  Note carefully that unlike the **link target** directive above, this directive has 2 colons.  (The only ReST and sphinx directives that are valid with one colon are **link target**s as shown above.)  Lone `::`, `:code:` or `.. code:` should not be used.
197* If you want to separate code into easier-to-understand sections you can do so with a single empty line.
198* For syntax highlighting appropriate to the language in the code block, specify the language after the directive.  Some examples are:
199
200  - `.. code-block:: c`,
201  - `.. code-block:: cpp`,
202  - `.. code-block:: python`,
203  - `.. code-block:: shell`,
204  - `.. code-block:: kconfig`,
205  - `.. code-block:: json`,
206  - `.. code-block:: yaml`,
207  - `.. code-block:: csharp` (or "cs"),
208  - `.. code-block:: vb.net`,
209  - `.. code-block:: dot` (graphviz),
210  - `.. code-block:: html`,
211  - `.. code-block:: css`,
212  - `.. code-block:: xml`,
213  - `.. code-block:: make`.
214
215The full set of supported lexers are listed here:  https://pygments.org/docs/lexers/ .
216
217
218### Bulleted Lists
219
220To create a bulleted list, do the following:
221
222    - First item description
223    - If you want to span multiple lines, indent subsequent
224      lines to align with item text like this.
225    - If you want to include a code block under a list item,
226      it must be intended to align with the list item like this:
227
228      .. code-block: python
229                                 <=== blank line here is important
230          # this is some code
231                                 <=== blank line here is important
232    - If you want to have nested bulleted lists, indent each
233      new level to align with its parent list item like this:
234                                 <=== blank line here is important
235      - level 2 item 1: text
236      - level 2 item 2: text
237                                 <=== blank line here is important
238    - Last list item.  Note that the nested list above is preceded
239      and followed by 1 blank line.
240
241All lists (including nested lists) **must** be preceded and followed with at least 1 blank line.  This is mandatory for the documentation-generation logic to process it correctly.
242
243
244### Referencing API Documentation
245
246If you want to reference portions of the LVGL code from the documentation (in .RST files) there are special directives to do this:
247
248    :cpp:func:`lv_init`
249    :c:macro:`LV_USE_FLEX`
250    :cpp:type:`lv_event_t`
251    :cpp:enum:`_lv_event_t`
252    :cpp:enumerator:`LV_EVENT_ALL`
253    :cpp:struct:`lv_image_dsc_t`
254    :cpp:union:`lv_style_value_t`
255
256There is a special directive when wanting to use a more complex expression.  For example when showing the arguments passed to a function.
257
258    :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX)`
259    :cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
260
261Arguments that are expressions (more than one word), or contain non-alphanumeric characters will cause the `:cpp:expr:` interpreted-text to fail.  Examples:
262
263    :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)`         <== arg with > 1 word
264    :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_*)`                 <== asterisk
265    :cpp:expr:`lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)`             <== asterisk
266    :cpp:expr:`lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)`  <== cast
267    :cpp:expr:`lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);`            <== ampersand & semicolon
268    :cpp:expr:`lv_obj_set_layout(widget, ...)`                         <== lone ellipsis
269
270For such examples, simply use reStructuredText literal markup like this:
271
272    ``lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)``
273    ``lv_obj_set_layout(widget, LV_LAYOUT_*)``
274    ``lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)``
275    ``lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)``
276    ``lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);``
277    ``lv_obj_set_layout(widget, ...)``
278
279
280