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