X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=550d8dec281e5eab9360bc78145e1d20e100909b;hb=770fabcd36ec11d64544e86ed7d2dda9f5c64daf;hp=097575ad7718e5434f99bdce1bac8417fc45da79;hpb=71ac639971d695c429cbf0241c508caae29b1e8a;p=dpdk.git
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 097575ad77..550d8dec28 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.
@@ -63,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:
@@ -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
@@ -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.