1.. _zephyr_doc:
2
3Documentation Generation
4########################
5
6These instructions will walk you through generating the Zephyr Project's
7documentation on your local system using the same documentation sources
8as we use to create the online documentation found at
9https://docs.zephyrproject.org
10
11.. _documentation-overview:
12
13Documentation overview
14**********************
15
16Zephyr Project content is written using the reStructuredText markup
17language (.rst file extension) with Sphinx extensions, and processed
18using Sphinx to create a formatted stand-alone website. Developers can
19view this content either in its raw form as .rst markup files, or you
20can generate the HTML content and view it with a web browser directly on
21your workstation. This same .rst content is also fed into the Zephyr
22Project's public website documentation area (with a different theme
23applied).
24
25You can read details about `reStructuredText`_, and `Sphinx`_ from
26their respective websites.
27
28The project's documentation contains the following items:
29
30* ReStructuredText source files used to generate documentation found at the
31  https://docs.zephyrproject.org website. Most of the reStructuredText sources
32  are found in the ``/doc`` directory, but others are stored within the
33  code source tree near their specific component (such as ``/samples`` and
34  ``/boards``)
35
36* Doxygen-generated material used to create all API-specific documents
37  also found at https://docs.zephyrproject.org
38
39* Script-generated material for kernel configuration options based on Kconfig
40  files found in the source code tree
41
42.. graphviz::
43   :caption: Schematic of the documentation build process
44
45   digraph {
46      rankdir=LR
47
48      images [shape="rectangle" label=".png, .jpg\nimages"]
49      rst [shape="rectangle" label="restructuredText\nfiles"]
50      conf [shape="rectangle" label="conf.py\nconfiguration"]
51      rtd [shape="rectangle" label="read-the-docs\ntheme"]
52      header [shape="rectangle" label="c header\ncomments"]
53      xml [shape="rectangle" label="XML"]
54      html [shape="rectangle" label="HTML\nweb site"]
55      sphinx[shape="ellipse" label="sphinx +\ndocutils"]
56      images -> sphinx
57      rst -> sphinx
58      conf -> sphinx
59      header -> doxygen
60      doxygen -> xml
61      xml-> sphinx
62      rtd -> sphinx
63      sphinx -> html
64   }
65
66
67The reStructuredText files are processed by the Sphinx documentation system,
68and make use of the doxygen-generated API material.
69Additional tools are required to generate the
70documentation locally, as described in the following sections.
71
72.. _documentation-processors:
73
74Installing the documentation processors
75***************************************
76
77Our documentation processing has been tested to run with:
78
79* Doxygen version 1.8.13
80* Graphviz 2.43
81* Latexmk version 4.56
82* All Python dependencies listed in the repository file
83  ``doc/requirements.txt``
84
85In order to install the documentation tools, first install Zephyr as
86described in :ref:`getting_started`. Then install additional tools
87that are only required to generate the documentation,
88as described below:
89
90.. doc_processors_installation_start
91
92.. tabs::
93
94   .. group-tab:: Linux
95
96      Common to all Linux installations, install the Python dependencies
97      required to build the documentation:
98
99      .. code-block:: console
100
101         pip install -U -r ~/zephyrproject/zephyr/doc/requirements.txt
102
103      On Ubuntu Linux:
104
105      .. code-block:: console
106
107         sudo apt-get install --no-install-recommends doxygen graphviz librsvg2-bin \
108         texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended imagemagick
109
110      On Fedora Linux:
111
112      .. code-block:: console
113
114         sudo dnf install doxygen graphviz texlive-latex latexmk \
115         texlive-collection-fontsrecommended librsvg2-tools ImageMagick
116
117      On Clear Linux:
118
119      .. code-block:: console
120
121         sudo swupd bundle-add texlive graphviz ImageMagick
122
123      On Arch Linux:
124
125      .. code-block:: console
126
127         sudo pacman -S graphviz doxygen librsvg texlive-core texlive-bin \
128         texlive-latexextra texlive-fontsextra imagemagick
129
130   .. group-tab:: macOS
131
132      Install the Python dependencies required to build the documentation:
133
134      .. code-block:: console
135
136         pip install -U -r ~/zephyrproject/zephyr/doc/requirements.txt
137
138      Use ``brew`` and ``tlmgr`` to install the tools:
139
140      .. code-block:: console
141
142         brew install doxygen graphviz mactex librsvg imagemagick
143         tlmgr install latexmk
144         tlmgr install collection-fontsrecommended
145
146   .. group-tab:: Windows
147
148      Install the Python dependencies required to build the documentation:
149
150      .. code-block:: console
151
152         pip install -U -r %HOMEPATH$\zephyrproject\zephyr\doc\requirements.txt
153
154      Open a ``cmd.exe`` window as **Administrator** and run the following command:
155
156      .. code-block:: console
157
158         choco install doxygen.install graphviz strawberryperl miktex rsvg-convert imagemagick
159
160      .. note::
161         On Windows, the Sphinx executable ``sphinx-build.exe`` is placed in
162         the ``Scripts`` folder of your Python installation path.
163         Depending on how you have installed Python, you might need to
164         add this folder to your ``PATH`` environment variable. Follow
165         the instructions in `Windows Python Path`_ to add those if needed.
166
167.. doc_processors_installation_end
168
169Documentation presentation theme
170********************************
171
172Sphinx supports easy customization of the generated documentation
173appearance through the use of themes. Replace the theme files and do
174another ``make html`` and the output layout and style is changed.
175The ``read-the-docs`` theme is installed as part of the
176:ref:`install_py_requirements` step you took in the getting started
177guide.
178
179Running the documentation processors
180************************************
181
182The ``/doc`` directory in your cloned copy of the Zephyr project git
183repo has all the .rst source files, extra tools, and Makefile for
184generating a local copy of the Zephyr project's technical documentation.
185Assuming the local Zephyr project copy is in a folder ``zephyr`` in your home
186folder, here are the commands to generate the html content locally:
187
188.. code-block:: console
189
190   # On Linux/macOS
191   cd ~/zephyr/doc
192   # On Windows
193   cd %userprofile%\zephyr\doc
194
195   # Use cmake to configure a Ninja-based build system:
196   cmake -GNinja -B_build .
197
198   # Enter the build directory
199   cd _build
200
201   # To generate HTML output, run ninja on the generated build system:
202   ninja html
203   # If you modify or add .rst files, run ninja again:
204   ninja html
205
206   # To generate PDF output, run ninja on the generated build system:
207   ninja pdf
208
209.. warning::
210
211   The documentation build system creates copies in the build
212   directory of every .rst file used to generate the documentation,
213   along with dependencies referenced by those .rst files.
214
215   This means that Sphinx warnings and errors refer to the **copies**,
216   and **not the version-controlled original files in Zephyr**. Be
217   careful to make sure you don't accidentally edit the copy of the
218   file in an error message, as these changes will not be saved.
219
220Depending on your development system, it will take up to 15 minutes to
221collect and generate the HTML content.  When done, you can view the HTML
222output with your browser started at ``doc/_build/html/index.html`` and
223if generated, the PDF file is available at ``doc/_build/latex/zephyr.pdf``.
224
225If you want to build the documentation from scratch just delete the contents
226of the build folder and run ``cmake`` and then ``ninja`` again.
227
228.. note::
229
230   If you add or remove a file from the documentation, you need to re-run CMake.
231
232On Unix platforms a convenience :zephyr_file:`doc/Makefile` can be used to
233build the documentation directly from there:
234
235.. code-block:: console
236
237   cd ~/zephyr/doc
238
239   # To generate HTML output
240   make html
241
242   # To generate PDF output
243   make pdf
244
245Developer-mode Document Building
246********************************
247
248When making and testing major changes to the documentation, we provide an option
249to temporarily stub-out the auto-generated Devicetree bindings documentation so
250the doc build process runs faster.
251
252To enable this mode, set the following option when invoking cmake::
253
254   -DDT_TURBO_MODE=1
255
256or invoke make with the following target::
257
258   cd ~/zephyr/doc
259
260   # To generate HTML output without detailed Kconfig
261   make html-fast
262
263Viewing generated documentation locally
264***************************************
265
266The generated HTML documentation can be hosted locally with python for viewing
267with a web browser:
268
269.. code-block:: console
270
271   $ python3 -m http.server -d _build/html
272
273.. note::
274
275   WSL2 users may need to explicitly bind the address to ``127.0.0.1`` in order
276   to be accessible from the host machine:
277
278   .. code-block:: console
279
280      $ python3 -m http.server -d _build/html --bind 127.0.0.1
281
282Alternatively, the documentation can be built with the ``make html-live``
283(or ``make html-live-fast``) command, which will build the documentation, host
284it locally, and watch the documentation directory for changes. When changes are
285observed, it will automatically rebuild the documentation and refresh the hosted
286files.
287
288Linking external Doxygen projects against Zephyr
289************************************************
290
291External projects that build upon Zephyr functionality and wish to refer to
292Zephyr documentation in Doxygen (through the use of @ref), can utilize the
293tag file exported at `zephyr.tag <../../doxygen/html/zephyr.tag>`_
294
295Once downloaded, the tag file can be used in a custom ``doxyfile.in`` as follows::
296
297   TAGFILES = "/path/to/zephyr.tag=https://docs.zephyrproject.org/latest/doxygen/html/"
298
299For additional information refer to `Doxygen External Documentation`_.
300
301
302.. _reStructuredText: http://sphinx-doc.org/rest.html
303.. _Sphinx: http://sphinx-doc.org/
304.. _Windows Python Path: https://docs.python.org/3/using/windows.html#finding-the-python-executable
305.. _Doxygen External Documentation: https://www.doxygen.nl/manual/external.html
306