X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=550d8dec281e5eab9360bc78145e1d20e100909b;hb=770fabcd36ec11d64544e86ed7d2dda9f5c64daf;hp=cb5ca0dc7b12aebfc143cbd554d224bc32cef08f;hpb=6bdae907647691fe2f380efcd281cc276fafb3d0;p=dpdk.git
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index cb5ca0dc7b..550d8dec28 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -1,4 +1,7 @@
-.. doc_guidelines:
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2018 The DPDK contributors
+
+.. _doc_guidelines:
DPDK Documentation Guidelines
=============================
@@ -19,7 +22,6 @@ The main directories that contain files related to documentation are shown below
|-- librte_acl
|-- librte_cfgfile
|-- librte_cmdline
- |-- librte_compat
|-- librte_eal
| |-- ...
...
@@ -34,18 +36,17 @@ The main directories that contain files related to documentation are shown below
|-- testpmd_app_ug
|-- rel_notes
|-- nics
- |-- xen
|-- ...
-The API documentation is built from `Doxygen `_ comments in the header files.
+The API documentation is built from `Doxygen `_ comments in the header files.
These files are mainly in the ``lib/librte_*`` directories although some of the Poll Mode Drivers in ``drivers/net``
are also documented with Doxygen.
The configuration files that are used to control the Doxygen output are in the ``doc/api`` directory.
The user guides such as *The Programmers Guide* and the *FreeBSD* and *Linux Getting Started* Guides are generated
-from RST markup text files using the `Sphinx `_ Documentation Generator.
+from RST markup text files using the `Sphinx `_ Documentation Generator.
These files are included in the ``doc/guides/`` directory.
The output is controlled by the ``doc/guides/conf.py`` file.
@@ -61,16 +62,27 @@ added to by the developer.
The Release Notes document which features have been added in the current and previous releases of DPDK and highlight
any known issues.
- The Releases Notes also contain notifications of features that will change ABI compatibility in the next major release.
+ The Releases Notes also contain notifications of features that will change ABI compatibility in the next release.
+
+ Developers should include updates to the Release Notes with patch sets that relate to any of the following sections:
+
+ * New Features
+ * Resolved Issues (see below)
+ * Known Issues
+ * API Changes
+ * ABI Changes
+ * Shared Library Versions
+
+ Resolved Issues should only include issues from previous releases that have been resolved in the current release.
+ Issues that are introduced and then fixed within a release cycle do not have to be included here.
+
+ Refer to the Release Notes from the previous DPDK release for the correct format of each section.
- Developers should update the Release Notes to add a short description of new or updated features.
- Developers should also update the Release Notes to add ABI announcements if necessary,
- (see :doc:`/contributing/versioning` for details).
* **API documentation**
The API documentation explains how to use the public DPDK functions.
- The `API index page `_ shows the generated API documentation with related groups of functions.
+ The `API index page `_ shows the generated API documentation with related groups of functions.
The API documentation should be updated via Doxygen comments when new functions are added.
@@ -131,7 +143,7 @@ The following dependencies must be installed to build the documentation:
* 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.
@@ -144,23 +156,25 @@ It can be installed as follows:
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
+ sudo dnf -y install python-pip
+ sudo pip install --upgrade sphinx
+ sudo pip install --upgrade sphinx_rtd_theme
- # Or, on any system with Python installed.
- sudo easy_install -U sphinx
-
-For further information on getting started with Sphinx see the `Sphinx Tutorial `_.
+For further information on getting started with Sphinx see the
+`Sphinx Getting Started `_.
.. Note::
@@ -176,7 +190,7 @@ It can be installed as follows:
sudo apt-get -y install inkscape
# Red Hat/Fedora.
- sudo yum -y install inkscape
+ sudo dnf -y install inkscape
`TexLive `_ is an installation package for Tex/LaTeX.
It is used to generate the PDF versions of the documentation.
@@ -185,13 +199,23 @@ The main required packages can be installed as follows:
.. 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 texlive-lang-greek
# Red Hat/Fedora, selective install.
- sudo yum -y install texlive-collection-latexextra \
- texlive-collection-fontsextra
+ sudo dnf -y install texlive-collection-latexextra texlive-greek-fontenc
+
+`Latexmk `_ is a perl script
+for running LaTeX for resolving cross references,
+and it also runs auxiliary programs like bibtex, makeindex if necessary, and dvips.
+It has also a number of other useful capabilities (see man 1 latexmk).
+
+.. code-block:: console
+
+ # Ubuntu/Debian.
+ sudo apt-get -y install latexmk
+
+ # Red Hat/Fedora.
+ sudo dnf -y install latexmk
Build commands
@@ -273,33 +297,21 @@ The additional guidelines below reiterate or expand upon those guidelines.
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:
+* 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.
- *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 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.
- *This is a new paragraph, since it is separated from the
- previous paragraph by a blank line.*
+ 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
@@ -323,7 +335,7 @@ Whitespace
Section Headers
~~~~~~~~~~~~~~~
-* Section headers should use the use the following underline formats::
+* Section headers should use the following underline formats::
Level 1 Heading
===============
@@ -371,12 +383,11 @@ Lists
#. 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.
@@ -449,8 +460,8 @@ Code and Literal block sections
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
@@ -466,9 +477,9 @@ Images
* The DPDK documentation contains some legacy images in PNG format.
These will be converted to SVG in time.
-* `Inkscape `_ is the recommended graphics editor for creating the images.
+* `Inkscape `_ 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.
@@ -585,7 +596,7 @@ Doxygen Guidelines
The DPDK API is documented using Doxygen comment annotations in the header files.
Doxygen is a very powerful tool, it is extremely configurable and with a little effort can be used to create expressive documents.
-See the `Doxygen website `_ for full details on how to use it.
+See the `Doxygen website `_ for full details on how to use it.
The following are some guidelines for use of Doxygen in the DPDK API documentation:
@@ -617,24 +628,19 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
.. 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.
@@ -660,7 +666,7 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
*/
In the API documentation the functions will be rendered as links, see the
- `online section of the rte_ethdev.h docs `_ that contains the above text.
+ `online section of the rte_ethdev.h docs `_ 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.