-.. doc_guidelines:
+.. _doc_guidelines:
DPDK Documentation Guidelines
=============================
* Sphinx (also called python-sphinx).
-* TexLive (at least TexLive-core, extra Latex support and extra fonts).
+* TexLive (at least TexLive-core and the extra Latex support).
* Inkscape.
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).
-It can be installed as follows:
+For full support with figure and table captioning the latest version of Sphinx can be installed as follows:
.. code-block:: console
# Ubuntu/Debian.
- sudo apt-get -y install python-sphinx
+ 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-sphinx
-
- # Or, on any system with Python installed.
- sudo easy_install -U sphinx
+ 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.
.. code-block:: console
# Ubuntu/Debian.
- sudo apt-get -y install texlive-latex-extra texlive-fonts-extra \
- texlive-fonts-recommended
-
+ sudo apt-get -y install texlive-latex-extra
# Red Hat/Fedora, selective install.
- sudo yum -y install texlive-collection-latexextra \
- texlive-collection-fontsextra
+ 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.
+* 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 would be rendered as follows:
+* 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.
- *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.*
+ Long literal command lines can be shown wrapped with backslashes. For
+ example::
- *This is a new paragraph, since it is separated from the
- previous paragraph by a blank line.*
-
-
-* 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 --txqflags=0x0 --disable-hw-vlan --enable-lro \
+ --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024 --txd=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
* The DPDK documentation contains some legacy images in PNG format.
These will be converted to SVG in time.
-* `Inkscape <inkscape.org>`_ is the recommended graphics editor for creating the images.
+* `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.
* @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`.
+ * `0000:01:00.0` or **virtual** device name like `net_pcap0`.
* @param port_id
* A pointer to a port identifier actually attached.
*
* 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.
git.droids-corp.org / dpdk.git / blobdiff