-.. doc_guidelines:
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2018 The DPDK contributors
+
+.. _doc_guidelines:
DPDK Documentation Guidelines
=============================
|-- testpmd_app_ug
|-- rel_notes
|-- nics
- |-- xen
|-- ...
* **API documentation**
The API documentation explains how to use the public DPDK functions.
- The `API index page <http://dpdk.org/doc/api/>`_ shows the generated API documentation with related groups of functions.
+ The `API index page <http://doc.dpdk.org/api/>`_ shows the generated API documentation with related groups of functions.
The API documentation should be updated via Doxygen comments when new functions are added.
sudo apt-get -y install doxygen
# Red Hat/Fedora.
- sudo yum -y install doxygen
+ sudo dnf -y install doxygen
`Sphinx`_ is a Python documentation tool for converting RST files to Html or to PDF (via LaTeX).
For full support with figure and table captioning the latest version of Sphinx can be installed as follows:
# Ubuntu/Debian.
sudo apt-get -y install python-pip
sudo pip install --upgrade sphinx
+ sudo pip install --upgrade sphinx_rtd_theme
# Red Hat/Fedora.
- sudo yum -y install python-pip
+ sudo dnf -y install python-pip
sudo pip install --upgrade sphinx
+ sudo pip install --upgrade sphinx_rtd_theme
For further information on getting started with Sphinx see the `Sphinx Tutorial <http://sphinx-doc.org/tutorial.html>`_.
sudo apt-get -y install inkscape
# Red Hat/Fedora.
- sudo yum -y install inkscape
+ sudo dnf -y install inkscape
`TexLive <http://www.tug.org/texlive/>`_ is an installation package for Tex/LaTeX.
It is used to generate the PDF versions of the documentation.
sudo apt-get -y install texlive-latex-extra
# Red Hat/Fedora, selective install.
- sudo yum -y install texlive-collection-latexextra
+ sudo dnf -y install texlive-collection-latexextra
Build commands
Line Length
~~~~~~~~~~~
-* The recommended style for the DPDK documentation is to put sentences on separate lines.
- This allows for easier reviewing of patches.
- Multiple sentences which are not separated by a blank line are joined automatically into paragraphs, for example::
-
- Here is an example sentence.
- Long sentences over the limit shown below can be wrapped onto
- a new line.
- These three sentences will be joined into the same paragraph.
-
- This is a new paragraph, since it is separated from the
- previous paragraph by a blank line.
-
- This would be rendered as follows:
-
- *Here is an example sentence.
- Long sentences over the limit shown below can be wrapped onto
- a new line.
- These three sentences will be joined into the same paragraph.*
+* Lines in sentences should be less than 80 characters and wrapped at
+ words. Multiple sentences which are not separated by a blank line are joined
+ automatically into paragraphs.
- *This is a new paragraph, since it is separated from the
- previous paragraph by a blank line.*
+* Lines in literal blocks **must** be less than 80 characters since
+ they are not wrapped by the document formatters and can exceed the page width
+ in PDF documents.
+ Long literal command lines can be shown wrapped with backslashes. For
+ example::
-* Long sentences should be wrapped at 120 characters +/- 10 characters. They should be wrapped at words.
-
-* Lines in literal blocks must by less than 80 characters since they aren't wrapped by the document formatters
- and can exceed the page width in PDF documents.
+ testpmd -l 2-3 -n 4 \
+ --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
+ -- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
+ --txd=1024 --rxd=1024
Whitespace
Section Headers
~~~~~~~~~~~~~~~
-* Section headers should use the use the following underline formats::
+* Section headers should use the following underline formats::
Level 1 Heading
===============
#. Item one.
- #. Item two is a long line that is wrapped and then indented
- to match the start of the e first line.
-
#. Item two is a long line that is wrapped and then indented to match
the start of the previous line.
+ #. Item three.
+
* Definition lists can be written with or without a bullet::
* Item one.
For long literal lines that exceed that limit try to wrap the text at sensible locations.
For example a long command line could be documented like this and still work if copied directly from the docs::
- build/app/testpmd -c7 -n3 --vdev=eth_pcap0,iface=eth0 \
- --vdev=eth_pcap1,iface=eth1 \
+ build/app/testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0 \
+ --vdev=net_pcap1,iface=eth1 \
-- -i --nb-cores=2 --nb-ports=2 \
--total-num-mbufs=2048
* `Inkscape <http://inkscape.org>`_ is the recommended graphics editor for creating the images.
Use some of the older images in ``doc/guides/prog_guide/img/`` as a template, for example ``mbuf1.svg``
- or ``ring-enqueue.svg``.
+ or ``ring-enqueue1.svg``.
* The SVG images should include a copyright notice, as an XML comment.
.. code-block:: c
/**
- * Attach a new Ethernet device specified by arguments.
- *
- * @param devargs
- * A pointer to a strings array describing the new device
- * to be attached. The strings should be a pci address like
- * `0000:01:00.0` or **virtual** device name like `eth_pcap0`.
- * @param port_id
- * A pointer to a port identifier actually attached.
+ * Try to take the lock.
*
+ * @param sl
+ * A pointer to the spinlock.
* @return
- * 0 on success and port_id is filled, negative on error.
+ * 1 if the lock is successfully taken; 0 otherwise.
*/
- int rte_eth_dev_attach(const char *devargs, uint8_t *port_id);
+ int rte_spinlock_trylock(rte_spinlock_t *sl);
* Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists.
For example the second line in the ``devargs`` parameter in the previous example will be rendered as:
- The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``eth_pcap0``.
+ The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``net_pcap0``.
* Use ``-`` instead of ``*`` for lists within the Doxygen comment since the latter can get confused with the comment delimiter.
*/
In the API documentation the functions will be rendered as links, see the
- `online section of the rte_ethdev.h docs <http://dpdk.org/doc/api/rte__ethdev_8h.html>`_ that contains the above text.
+ `online section of the rte_ethdev.h docs <http://doc.dpdk.org/api/rte__ethdev_8h.html>`_ that contains the above text.
* The ``@see`` keyword can be used to create a *see also* link to another file or library.
This directive should be placed on one line at the bottom of the documentation section.
git.droids-corp.org / dpdk.git / blobdiff