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