X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=27e4b13be1c47fc13854c869e34311e9ae492de9;hb=2097255731d5d3724063e9acf18b23bcbe4b7bac;hp=6a075553d8bc190512fc516d2afdd54e6bfd14b7;hpb=77c79de08c15ddf08b7f422ef797b434ff897d64;p=dpdk.git
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 6a075553d8..27e4b13be1 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -22,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
| |-- ...
...
@@ -40,14 +39,14 @@ The main directories that contain files related to documentation are shown below
|-- ...
-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.
@@ -83,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.
@@ -174,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::
@@ -199,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
@@ -297,8 +310,8 @@ Line Length
testpmd -l 2-3 -n 4 \
--vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
- -- -i --txqflags=0x0 --enable-hw-vlan --enable-lro \
- --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024 --txd=1024
+ -- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
+ --txd=1024 --rxd=1024
Whitespace
@@ -583,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:
@@ -615,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:
@@ -658,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.