X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=a4e6be6aca69598e3b390987a2e0cf6d7da449f0;hb=71b09bd95096610aaddb69497297103a129e0e7c;hp=550d8dec281e5eab9360bc78145e1d20e100909b;hpb=e85373edf0857f1774f6e519bd2af669d6eaeb2b;p=dpdk.git
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 550d8dec28..a4e6be6aca 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -82,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.
@@ -164,14 +164,10 @@ For full support with figure and table captioning the latest version of Sphinx c
.. code-block:: console
# Ubuntu/Debian.
- sudo apt-get -y install python-pip
- sudo pip install --upgrade sphinx
- sudo pip install --upgrade sphinx_rtd_theme
+ sudo apt-get -y install python3-sphinx python3-sphinx-rtd-theme
# Red Hat/Fedora.
- sudo dnf -y install python-pip
- sudo pip install --upgrade sphinx
- sudo pip install --upgrade sphinx_rtd_theme
+ sudo dnf -y install python3-sphinx python3-sphinx_rtd_theme
For further information on getting started with Sphinx see the
`Sphinx Getting Started `_.
@@ -222,25 +218,14 @@ Build commands
~~~~~~~~~~~~~~
The documentation is built using the standard DPDK build system.
-Some examples are shown below:
-* Generate all the documentation targets::
+To build the documentation::
- make doc
+ ninja -C build doc
-* Generate the Doxygen API documentation in Html::
+See :doc:`../linux_gsg/build_dpdk` for more detail on compiling DPDK with meson.
- make doc-api-html
-
-* Generate the guides documentation in Html::
-
- make doc-guides-html
-
-* Generate the guides documentation in Pdf::
-
- make doc-guides-pdf
-
-The output of these commands is generated in the ``build`` directory::
+The output is generated in the ``build`` directory::
build/doc
|-- html
@@ -255,10 +240,6 @@ The output of these commands is generated in the ``build`` directory::
Make sure to fix any Sphinx or Doxygen warnings when adding or updating documentation.
-The documentation output files can be removed as follows::
-
- make doc-clean
-
Document Guidelines
-------------------
@@ -308,7 +289,7 @@ Line Length
Long literal command lines can be shown wrapped with backslashes. For
example::
- testpmd -l 2-3 -n 4 \
+ dpdk-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
@@ -460,7 +441,7 @@ 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 -l 0-2 -n3 --vdev=net_pcap0,iface=eth0 \
+ .//app/dpdk-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
@@ -561,14 +542,14 @@ Hyperlinks
~~~~~~~~~~
* Links to external websites can be plain URLs.
- The following is rendered as http://dpdk.org::
+ The following is rendered as https://dpdk.org::
- http://dpdk.org
+ https://dpdk.org
* They can contain alternative text.
- The following is rendered as `Check out DPDK `_::
+ The following is rendered as `Check out DPDK `_::
- `Check out DPDK `_
+ `Check out DPDK `_
* An internal link can be generated by placing labels in the document with the format ``.. _label_name``.
@@ -666,7 +647,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.
@@ -743,9 +724,5 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
/** Array of physical page addresses for the mempool buffer. */
phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
-* Check for Doxygen warnings in new code by checking the API documentation build::
-
- make doc-api-html >/dev/null
-
* Read the rendered section of the documentation that you have added for correctness, clarity and consistency
with the surrounding text.