X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=550d8dec281e5eab9360bc78145e1d20e100909b;hb=770fabcd36ec11d64544e86ed7d2dda9f5c64daf;hp=6d4c2777e90fce75824bef5bd1092114bf274e70;hpb=5fc07e3eb7599d5b5995e28f5d727367a7fa9c0e;p=dpdk.git
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 6d4c2777e9..550d8dec28 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -1,3 +1,6 @@
+.. 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,7 +62,7 @@ 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:
@@ -81,7 +82,7 @@ added to by the developer.
* **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.
@@ -172,7 +173,8 @@ For full support with figure and table captioning the latest version of Sphinx c
sudo pip install --upgrade sphinx
sudo pip install --upgrade sphinx_rtd_theme
-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::
@@ -197,10 +199,23 @@ The main required packages can be installed as follows:
.. code-block:: console
# Ubuntu/Debian.
- sudo apt-get -y install texlive-latex-extra
+ sudo apt-get -y install texlive-latex-extra texlive-lang-greek
# Red Hat/Fedora, selective install.
- sudo dnf -y install texlive-collection-latexextra
+ 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
@@ -282,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::
+* 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::
- 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.*
-
- *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 --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
+ --txd=1024 --rxd=1024
Whitespace
@@ -332,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
===============
@@ -380,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.
@@ -458,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
@@ -477,7 +479,7 @@ 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.
@@ -594,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:
@@ -626,19 +628,14 @@ 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 `net_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:
@@ -669,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.