xref: /dpdk/doc/guides/contributing/documentation.rst (revision c56185fc183fc0532d2f03aaf04bbf0989ea91a5)
1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright 2018 The DPDK contributors
3
4.. _doc_guidelines:
5
6DPDK Documentation Guidelines
7=============================
8
9This document outlines the guidelines for writing the DPDK Guides and API documentation in RST and Doxygen format.
10
11It also explains the structure of the DPDK documentation and how to build it.
12
13
14Structure of the Documentation
15------------------------------
16
17The DPDK source code repository contains input files to build the API documentation and User Guides.
18
19The main directories that contain files related to documentation are shown below::
20
21   lib
22   |-- acl
23   |-- cfgfile
24   |-- cmdline
25   |-- eal
26   |   |-- ...
27   ...
28   doc
29   |-- api
30   +-- guides
31       |-- freebsd_gsg
32       |-- linux_gsg
33       |-- prog_guide
34       |-- sample_app_ug
35       |-- guidelines
36       |-- testpmd_app_ug
37       |-- rel_notes
38       |-- nics
39       |-- ...
40
41
42The API documentation is built from `Doxygen <http://www.doxygen.nl>`_ comments in the header files.
43These files are mainly in the ``lib/*`` directories although some of the Poll Mode Drivers in ``drivers/net``
44are also documented with Doxygen.
45
46The configuration files that are used to control the Doxygen output are in the ``doc/api`` directory.
47
48The user guides such as *The Programmers Guide* and the *FreeBSD* and *Linux Getting Started* Guides are generated
49from RST markup text files using the `Sphinx <http://sphinx-doc.org>`_ Documentation Generator.
50
51These files are included in the ``doc/guides/`` directory.
52The output is controlled by the ``doc/guides/conf.py`` file.
53
54
55Role of the Documentation
56-------------------------
57
58The following items outline the roles of the different parts of the documentation and when they need to be updated or
59added to by the developer.
60
61* **Release Notes**
62
63  The Release Notes document which features have been added in the current and previous releases of DPDK and highlight
64  any known issues.
65  The Releases Notes also contain notifications of features that will change ABI compatibility in the next release.
66
67  Developers should include updates to the Release Notes with patch sets that relate to any of the following sections:
68
69  * New Features
70  * Resolved Issues (see below)
71  * Known Issues
72  * API Changes
73  * ABI Changes
74  * Shared Library Versions
75
76  Resolved Issues should only include issues from previous releases that have been resolved in the current release.
77  Issues that are introduced and then fixed within a release cycle do not have to be included here.
78
79  Refer to the Release Notes from the previous DPDK release for the correct format of each section.
80
81
82* **API documentation**
83
84  The API documentation explains how to use the public DPDK functions.
85  The `API index page <https://doc.dpdk.org/api/>`_ shows the generated API documentation with related groups of functions.
86
87  The API documentation should be updated via Doxygen comments when new functions are added.
88
89* **Getting Started Guides**
90
91  The Getting Started Guides show how to install and configure DPDK and how to run DPDK based applications on different OSes.
92
93  A Getting Started Guide should be added when DPDK is ported to a new OS.
94
95* **The Programmers Guide**
96
97  The Programmers Guide explains how the API components of DPDK such as the EAL, Memzone, Rings and the Hash Library work.
98  It also describes some of the higher level functionality such as Packet Distributor and Packet Framework.
99  It also shows the build system and explains how to add applications.
100
101  The Programmers Guide should be expanded when new functionality is added to DPDK.
102
103* **App Guides**
104
105  The app guides document the DPDK applications in the ``app`` directory such as ``testpmd``.
106
107  The app guides should be updated if functionality is changed or added.
108
109* **Sample App Guides**
110
111  The sample app guides document the DPDK example applications in the examples directory.
112  Generally they demonstrate a major feature such as L2 or L3 Forwarding, Multi Process or Power Management.
113  They explain the purpose of the sample application, how to run it and step through some of the code to explain the
114  major functionality.
115
116  A new sample application should be accompanied by a new sample app guide.
117  The guide for the Skeleton Forwarding app is a good starting reference.
118
119* **Network Interface Controller Drivers**
120
121  The NIC Drivers document explains the features of the individual Poll Mode Drivers, such as software requirements,
122  configuration and initialization.
123
124  New documentation should be added for new Poll Mode Drivers.
125
126* **Guidelines**
127
128  The guideline documents record community process, expectations and design directions.
129
130  They can be extended, amended or discussed by submitting a patch and getting community approval.
131
132
133Building the Documentation
134--------------------------
135
136Dependencies
137~~~~~~~~~~~~
138
139The following dependencies must be installed to build the documentation:
140
141* Doxygen.
142* Sphinx (also called python-sphinx).
143
144`Doxygen`_ generates documentation from commented source code.
145It can be installed as follows:
146
147.. code-block:: console
148
149   # Ubuntu/Debian.
150   sudo apt-get -y install doxygen
151
152   # Red Hat/Fedora.
153   sudo dnf     -y install doxygen
154
155`Sphinx`_ is a Python documentation tool for converting RST files to HTML.
156For full support with figure and table captioning the latest version of Sphinx can be installed as follows:
157
158.. code-block:: console
159
160   # Ubuntu/Debian.
161   sudo apt-get -y install python3-sphinx python3-sphinx-rtd-theme
162
163   # Red Hat/Fedora.
164   sudo dnf     -y install python3-sphinx python3-sphinx_rtd_theme
165
166For further information on getting started with Sphinx see the
167`Sphinx Getting Started <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
168
169.. Note::
170
171   To get full support for Figure and Table numbering it is best to install Sphinx 1.3.1 or later.
172
173
174Build commands
175~~~~~~~~~~~~~~
176
177The documentation is built using the standard DPDK build system.
178
179To build the documentation::
180
181   ninja -C build doc
182
183See :doc:`../linux_gsg/build_dpdk` for more detail on compiling DPDK with meson.
184
185The output is generated in the directory ``build/doc/``, with:
186
187* HTML versions of the guide docs, e.g. Getting Started Guides, Programmers Guide, in ``build/doc/guides/html``
188* HTML version of the API documentation in ``build/doc/api/html``
189* Man-page version of the API documentation in ``build/doc/api/man``.
190  If not installing DPDK system-wise, these pages can be accessed by adding this directory to the ``MANPATH`` environment variable.
191  For example:
192
193.. code-block:: console
194
195   export MANPATH=:/path/to/build/doc/api/man
196
197.. Note::
198
199   Make sure to fix any Sphinx or Doxygen warnings when adding or updating documentation.
200
201
202Document Guidelines
203-------------------
204
205Here are some guidelines in relation to the style of the documentation:
206
207* Document the obvious as well as the obscure since it won't always be obvious to the reader.
208  For example an instruction like "Set up 64 2MB Hugepages" is better when followed by a sample commandline or a link to
209  the appropriate section of the documentation.
210
211* Use American English spellings throughout.
212  This can be checked using the ``aspell`` utility::
213
214       aspell --lang=en_US --check doc/guides/sample_app_ug/mydoc.rst
215
216
217RST Guidelines
218--------------
219
220The RST (reStructuredText) format is a plain text markup format
221that can be converted to HTML or other formats.
222It is most closely associated with Python but it can be used to document any language.
223It is used in DPDK to document everything apart from the API.
224
225The Sphinx documentation contains a very useful `RST Primer <http://sphinx-doc.org/rest.html#rst-primer>`_ which is a
226good place to learn the minimal set of syntax required to format a document.
227
228The official `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ website contains the specification for the
229RST format and also examples of how to use it.
230However, for most developers the RST Primer is a better resource.
231
232The most common guidelines for writing RST text are detailed in the
233`Documenting Python <https://docs.python.org/devguide/documenting.html>`_ guidelines.
234The additional guidelines below reiterate or expand upon those guidelines.
235
236
237Line Length
238~~~~~~~~~~~
239
240* Lines in sentences should be less than 80 characters and wrapped at
241  words. Multiple sentences which are not separated by a blank line are joined
242  automatically into paragraphs.
243
244* Lines in literal blocks should be less than 80 characters
245  since they are not wrapped by the document formatters.
246
247  Long literal command lines can be shown wrapped with backslashes. For
248  example::
249
250     dpdk-testpmd -l 2-3 -n 4 \
251             --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
252             -- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
253             --txd=1024 --rxd=1024
254
255
256Whitespace
257~~~~~~~~~~
258
259* Standard RST indentation is 3 spaces.
260  Code can be indented 4 spaces, especially if it is copied from source files.
261
262* No tabs.
263  Convert tabs in embedded code to 4 or 8 spaces.
264
265* No trailing whitespace.
266
267* Add 2 blank lines before each section header.
268
269* Add 1 blank line after each section header.
270
271* Add 1 blank line between each line of a list.
272
273
274Section Headers
275~~~~~~~~~~~~~~~
276
277* Section headers should use the following underline formats::
278
279   Level 1 Heading
280   ===============
281
282
283   Level 2 Heading
284   ---------------
285
286
287   Level 3 Heading
288   ~~~~~~~~~~~~~~~
289
290
291   Level 4 Heading
292   ^^^^^^^^^^^^^^^
293
294
295* Level 4 headings should be used sparingly.
296
297* The underlines should match the length of the text.
298
299* In general, the heading should be less than 80 characters, for conciseness.
300
301* As noted above:
302
303   * Add 2 blank lines before each section header.
304
305   * Add 1 blank line after each section header.
306
307
308Lists
309~~~~~
310
311* Bullet lists should be formatted with a leading ``*`` as follows::
312
313     * Item one.
314
315     * Item two is a long line that is wrapped and then indented to match
316       the start of the previous line.
317
318     * One space character between the bullet and the text is preferred.
319
320* Numbered lists can be formatted with a leading number but the preference is to use ``#.`` which will give automatic numbering.
321  This is more convenient when adding or removing items::
322
323     #. Item one.
324
325     #. Item two is a long line that is wrapped and then indented to match
326        the start of the previous line.
327
328     #. Item three.
329
330* Definition lists can be written with or without a bullet::
331
332     * Item one.
333
334       Some text about item one.
335
336     * Item two.
337
338       Some text about item two.
339
340* All lists, and sub-lists, must be separated from the preceding text by a blank line.
341  This is a syntax requirement.
342
343* All list items should be separated by a blank line for readability.
344
345
346Code and Literal block sections
347~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
348
349* Inline text that is required to be rendered with a fixed width font should be enclosed in backquotes like this:
350  \`\`text\`\`, so that it appears like this: ``text``.
351
352* Fixed width, literal blocks of texts should be indented at least 3 spaces and prefixed with ``::`` like this::
353
354     Here is some fixed width text::
355
356        0x0001 0x0001 0x00FF 0x00FF
357
358* It is also possible to specify an encoding for a literal block using the ``.. code-block::`` directive so that syntax
359  highlighting can be applied.
360  Examples of supported highlighting are::
361
362     .. code-block:: console
363     .. code-block:: c
364     .. code-block:: python
365     .. code-block:: diff
366     .. code-block:: none
367
368  That can be applied as follows::
369
370      .. code-block:: c
371
372         #include<stdio.h>
373
374         int main() {
375
376            printf("Hello World\n");
377
378            return 0;
379         }
380
381  Which would be rendered as:
382
383  .. code-block:: c
384
385      #include<stdio.h>
386
387      int main() {
388
389         printf("Hello World\n");
390
391         return 0;
392      }
393
394* Code snippets can also be included directly from the code using the ``literalinclude`` block.
395  Using this block instead of a code block will ensure that the code snippets
396  shown in the documentation are always up to date with the code.
397
398  The following will include a snippet from the skeleton sample app::
399
400      .. literalinclude:: ../../../examples/skeleton/basicfwd.c
401         :language: c
402         :start-after: Display the port MAC address.
403         :end-before: Enable RX in promiscuous mode for the Ethernet device.
404         :dedent: 1
405
406  This would be rendered as:
407
408  .. literalinclude:: ../../../examples/skeleton/basicfwd.c
409     :language: c
410     :start-after: Display the port MAC address.
411     :end-before: Enable RX in promiscuous mode for the Ethernet device.
412     :dedent: 1
413
414  Specifying ``:language:`` will enable syntax highlighting for the specified language.
415  ``:dedent:`` is used in this example to remove 1 leading tab from each line of the snippet.
416
417* ``start-after`` and ``end-before`` can use any text within a given file,
418  however it may be difficult to find unique text within your code to mark the
419  start and end of your snippets. In these cases, it is recommended to include
420  explicit tags in your code to denote these locations for documentation purposes.
421  The accepted format for these comments is:
422
423     * Before the code snippet, create a new comment which is a sentence explaining
424       what the code snippet contains. The comment is terminated with a scissors ``8<``.
425     * After the code snippet, create another new comment which starts with a
426       scissors ``>8``, then ``End of`` and the first comment repeated.
427     * The scissors should be orientated as shown to make it clear what code is being snipped.
428
429  This can be done as follows:
430
431  .. code-block:: c
432
433    /* Example feature being documented. 8< */
434    foo(bar);
435    /* >8 End of example feature being documented. */
436
437  ``foo(bar);`` could then be included in the docs using::
438
439      .. literalinclude:: ../../../examples/sample_app/main.c
440         :language: c
441         :start-after: Example feature being documented. 8<
442         :end-before: >8 End of example feature being documented.
443
444  If a multiline comment is needed before the snippet,
445  then the last line of the multiline comment should be in the same format as
446  the first comment shown in the example.
447
448* More information about the ``literalinclude`` block can be found within the
449  `Sphinx Documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=literalinclude#directive-literalinclude>`_.
450
451* The default encoding for a literal block using the simplified ``::``
452  directive is ``none``.
453
454* Lines in literal blocks should be less than 80 characters.
455  For long literal lines, try to wrap the text at sensible locations.
456  For example a long command line could be documented like this and still work if copied directly from the docs::
457
458     ./<build_dir>/app/dpdk-testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0    \
459                               --vdev=net_pcap1,iface=eth1     \
460                               -- -i --nb-cores=2 --nb-ports=2 \
461                                  --total-num-mbufs=2048
462
463* Long lines that cannot be wrapped, such as application output, should be truncated to be less than 80 characters.
464
465
466Images
467~~~~~~
468
469* All images should be in SVG scalar graphics format.
470  They should be true SVG XML files and should not include binary formats embedded in a SVG wrapper.
471
472* The DPDK documentation contains some legacy images in PNG format.
473  These will be converted to SVG in time.
474
475* `Inkscape <http://inkscape.org>`_ is the recommended graphics editor for creating the images.
476  Use some of the older images in ``doc/guides/prog_guide/img/`` as a template, for example ``mbuf1.svg``
477  or ``ring-enqueue1.svg``.
478
479* The SVG images should include a copyright notice, as an XML comment.
480
481* Images in the documentation should be formatted as follows:
482
483   * The image should be preceded by a label in the format ``.. _figure_XXXX:`` with a leading underscore and
484     where ``XXXX`` is a unique descriptive name.
485
486   * Images should be included using the ``.. figure::`` directive and the file type should be set to ``*`` (not ``.svg``).
487     This allows the format of the image to be changed if required, without updating the documentation.
488
489   * Images must have a caption as part of the ``.. figure::`` directive.
490
491* Here is an example of the previous three guidelines::
492
493     .. _figure_mempool:
494
495     .. figure:: img/mempool.*
496
497        A mempool in memory with its associated ring.
498
499.. _mock_label:
500
501* Images can then be linked to using the ``:numref:`` directive::
502
503     The mempool layout is shown in :numref:`figure_mempool`.
504
505  This would be rendered as: *The mempool layout is shown in* :ref:`Fig 6.3 <mock_label>`.
506
507  **Note**: The ``:numref:`` directive requires Sphinx 1.3.1 or later.
508  With earlier versions it will still be rendered as a link but won't have an automatically generated number.
509
510* The caption of the image can be generated, with a link, using the ``:ref:`` directive::
511
512     :ref:`figure_mempool`
513
514  This would be rendered as: *A mempool in memory with its associated ring.*
515
516Tables
517~~~~~~
518
519* RST tables should be used sparingly.
520  They are hard to format and to edit, and the same information
521  can usually be shown just as clearly with a definition or bullet list.
522
523* Tables in the documentation should be formatted as follows:
524
525   * The table should be preceded by a label in the format ``.. _table_XXXX:`` with a leading underscore and where
526     ``XXXX`` is a unique descriptive name.
527
528   * Tables should be included using the ``.. table::`` directive and must have a caption.
529
530* Here is an example of the previous two guidelines::
531
532     .. _table_qos_pipes:
533
534     .. table:: Sample configuration for QOS pipes.
535
536        +----------+----------+----------+
537        | Header 1 | Header 2 | Header 3 |
538        |          |          |          |
539        +==========+==========+==========+
540        | Text     | Text     | Text     |
541        +----------+----------+----------+
542        | ...      | ...      | ...      |
543        +----------+----------+----------+
544
545* Tables can be linked to using the ``:numref:`` and ``:ref:`` directives, as shown in the previous section for images.
546  For example::
547
548     The QOS configuration is shown in :numref:`table_qos_pipes`.
549
550
551.. _links:
552
553Hyperlinks
554~~~~~~~~~~
555
556* Links to external websites can be plain URLs.
557  The following is rendered as https://dpdk.org::
558
559     https://dpdk.org
560
561* They can contain alternative text.
562  The following is rendered as `Check out DPDK <https://dpdk.org>`_::
563
564     `Check out DPDK <https://dpdk.org>`_
565
566* An internal link can be generated by placing labels in the document with the format ``.. _label_name``.
567
568* The following links to the top of this section: :ref:`links`::
569
570     .. _links:
571
572     Hyperlinks
573     ~~~~~~~~~~
574
575     * The following links to the top of this section: :ref:`links`:
576
577.. Note::
578
579   The label must have a leading underscore but the reference to it must omit it.
580   This is a frequent cause of errors and warnings.
581
582* The use of a label is preferred since it works across files and will still work if the header text changes.
583
584
585.. _doxygen_guidelines:
586
587Doxygen Guidelines
588------------------
589
590The DPDK API is documented using Doxygen comment annotations in the header files.
591Doxygen is a very powerful tool, it is extremely configurable and with a little effort can be used to create expressive documents.
592See the `Doxygen website <http://www.doxygen.nl>`_ for full details on how to use it.
593
594The following are some guidelines for use of Doxygen in the DPDK API documentation:
595
596* New libraries that are documented with Doxygen should be added to the Doxygen configuration file: ``doc/api/doxy-api.conf``.
597  It is only required to add the directory that contains the files.
598  It isn't necessary to explicitly name each file since the configuration matches all ``rte_*.h`` files in the directory.
599
600* Use proper capitalization and punctuation in the Doxygen comments since they will become sentences in the documentation.
601  This in particular applies to single line comments, which is the case the is most often forgotten.
602
603* Use ``@`` style Doxygen commands instead of ``\`` style commands.
604
605* Add a general description of each library at the head of the main header files:
606
607  .. code-block:: c
608
609      /**
610       * @file
611       * RTE Mempool.
612       *
613       * A memory pool is an allocator of fixed-size object. It is
614       * identified by its name, and uses a ring to store free objects.
615       * ...
616       */
617
618* Document the purpose of a function, the parameters used and the return
619  value:
620
621  .. code-block:: c
622
623     /**
624      * Try to take the lock.
625      *
626      * @param sl
627      *   A pointer to the spinlock.
628      * @return
629      *   1 if the lock is successfully taken; 0 otherwise.
630      */
631     int rte_spinlock_trylock(rte_spinlock_t *sl);
632
633* Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists.
634  For example the second line in the ``devargs`` parameter in the previous example will be rendered as:
635
636     The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``net_pcap0``.
637
638* Use ``-`` instead of ``*`` for lists within the Doxygen comment since the latter can get confused with the comment delimiter.
639
640* Add an empty line between the function description, the ``@params`` and ``@return`` for readability.
641
642* Place the ``@params`` description on separate line and indent it by 2 spaces.
643  (It would be better to use no indentation since this is more common and also because checkpatch complains about leading
644  whitespace in comments.
645  However this is the convention used in the existing DPDK code.)
646
647* Documented functions can be linked to simply by adding ``()`` to the function name:
648
649  .. code-block:: c
650
651      /**
652       * The functions exported by the application Ethernet API to setup
653       * a device designated by its port identifier must be invoked in
654       * the following order:
655       *     - rte_eth_dev_configure()
656       *     - rte_eth_tx_queue_setup()
657       *     - rte_eth_rx_queue_setup()
658       *     - rte_eth_dev_start()
659       */
660
661  In the API documentation the functions will be rendered as links, see the
662  `online section of the rte_ethdev.h docs <https://doc.dpdk.org/api/rte__ethdev_8h.html>`_ that contains the above text.
663
664* The ``@see`` keyword can be used to create a *see also* link to another file or library.
665  This directive should be placed on one line at the bottom of the documentation section.
666
667  .. code-block:: c
668
669     /**
670      * ...
671      *
672      * Some text that references mempools.
673      *
674      * @see eal_memzone.c
675      */
676
677* Doxygen supports two types of comments for documenting variables, constants and members: prefix and postfix:
678
679  .. code-block:: c
680
681     /** This is a prefix comment. */
682     #define RTE_FOO_ERROR  0x023.
683
684     #define RTE_BAR_ERROR  0x024. /**< This is a postfix comment. */
685
686* Postfix comments are preferred for struct members and constants if they can be documented in the same way:
687
688  .. code-block:: c
689
690     struct rte_eth_stats {
691         uint64_t ipackets; /**< Total number of received packets. */
692         uint64_t opackets; /**< Total number of transmitted packets.*/
693         uint64_t ibytes;   /**< Total number of received bytes. */
694         uint64_t obytes;   /**< Total number of transmitted bytes. */
695         uint64_t imissed;  /**< Total of RX missed packets. */
696         uint64_t ibadcrc;  /**< Total of RX packets with CRC error. */
697         uint64_t ibadlen;  /**< Total of RX packets with bad length. */
698     }
699
700  Note: postfix comments should be aligned with spaces not tabs in accordance
701  with the :ref:`coding_style`.
702
703* If a single comment type can't be used, due to line length limitations then
704  prefix comments should be preferred.
705  For example this section of the code contains prefix comments, postfix comments on the same line and postfix
706  comments on a separate line:
707
708  .. code-block:: c
709
710     /** Number of elements in the elt_pa array. */
711     uint32_t    pg_num __rte_cache_aligned;
712     uint32_t    pg_shift;     /**< LOG2 of the physical pages. */
713     uintptr_t   pg_mask;      /**< Physical page mask value. */
714     uintptr_t   elt_va_start;
715     /**< Virtual address of the first mempool object. */
716     uintptr_t   elt_va_end;
717     /**< Virtual address of the <size + 1> mempool object. */
718     phys_addr_t elt_pa[1];
719     /**< Array of physical page addresses for the mempool buffer. */
720
721  This doesn't have an effect on the rendered documentation but it is confusing for the developer reading the code.
722  It this case it would be clearer to use prefix comments throughout:
723
724  .. code-block:: c
725
726     /** Number of elements in the elt_pa array. */
727     uint32_t    pg_num __rte_cache_aligned;
728     /** LOG2 of the physical pages. */
729     uint32_t    pg_shift;
730     /** Physical page mask value. */
731     uintptr_t   pg_mask;
732     /** Virtual address of the first mempool object. */
733     uintptr_t   elt_va_start;
734     /** Virtual address of the <size + 1> mempool object. */
735     uintptr_t   elt_va_end;
736     /** Array of physical page addresses for the mempool buffer. */
737     phys_addr_t elt_pa[1];
738
739* Read the rendered section of the documentation that you have added for correctness, clarity and consistency
740  with the surrounding text.
741