git.droids-corp.org
/
dpdk.git
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
net/enic: fix MAC address add and remove
[dpdk.git]
/
doc
/
guides
/
contributing
/
documentation.rst
diff --git
a/doc/guides/contributing/documentation.rst
b/doc/guides/contributing/documentation.rst
index
7f5f061
..
f90a3dd
100644
(file)
--- a/
doc/guides/contributing/documentation.rst
+++ b/
doc/guides/contributing/documentation.rst
@@
-1,4
+1,4
@@
-.. doc_guidelines:
+..
_
doc_guidelines:
DPDK Documentation Guidelines
=============================
DPDK Documentation Guidelines
=============================
@@
-142,7
+142,7
@@
The following dependencies must be installed to build the documentation:
* Sphinx (also called python-sphinx).
* 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.
* Inkscape.
@@
-155,21
+155,22
@@
It can be installed as follows:
sudo apt-get -y install doxygen
# Red Hat/Fedora.
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).
`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.
.. 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.
# Red Hat/Fedora.
- sudo yum -y install python-sphinx
-
- # Or, on any system with Python installed.
- sudo easy_install -U sphinx
+ sudo dnf -y install python-pip
+ sudo pip install --upgrade sphinx
+ sudo pip install --upgrade sphinx_rtd_theme
For further information on getting started with Sphinx see the `Sphinx Tutorial <http://sphinx-doc.org/tutorial.html>`_.
For further information on getting started with Sphinx see the `Sphinx Tutorial <http://sphinx-doc.org/tutorial.html>`_.
@@
-187,7
+188,7
@@
It can be installed as follows:
sudo apt-get -y install inkscape
# Red Hat/Fedora.
sudo apt-get -y install inkscape
# Red Hat/Fedora.
- sudo
yum
-y install inkscape
+ sudo
dnf
-y install inkscape
`TexLive <http://www.tug.org/texlive/>`_ is an installation package for Tex/LaTeX.
It is used to generate the PDF versions of the documentation.
`TexLive <http://www.tug.org/texlive/>`_ is an installation package for Tex/LaTeX.
It is used to generate the PDF versions of the documentation.
@@
-196,13
+197,10
@@
The main required packages can be installed as follows:
.. code-block:: console
# Ubuntu/Debian.
.. 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
# Red Hat/Fedora, selective install.
# Red Hat/Fedora, selective install.
- sudo yum -y install texlive-collection-latexextra \
- texlive-collection-fontsextra
+ sudo dnf -y install texlive-collection-latexextra
Build commands
Build commands
@@
-334,7
+332,7
@@
Whitespace
Section Headers
~~~~~~~~~~~~~~~
Section Headers
~~~~~~~~~~~~~~~
-* Section headers should use the
use the
following underline formats::
+* Section headers should use the following underline formats::
Level 1 Heading
===============
Level 1 Heading
===============
@@
-382,12
+380,11
@@
Lists
#. Item one.
#. 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 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.
* Definition lists can be written with or without a bullet::
* Item one.
@@
-460,8
+457,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::
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 -c7 -n3 --vdev=
net
_pcap0,iface=eth0 \
+ --vdev=
net
_pcap1,iface=eth1 \
-- -i --nb-cores=2 --nb-ports=2 \
--total-num-mbufs=2048
-- -i --nb-cores=2 --nb-ports=2 \
--total-num-mbufs=2048
@@
-479,7
+476,7
@@
Images
* `Inkscape <http://inkscape.org>`_ 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``
* `Inkscape <http://inkscape.org>`_ 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-enqueue
1
.svg``.
* The SVG images should include a copyright notice, as an XML comment.
* The SVG images should include a copyright notice, as an XML comment.
@@
-633,7
+630,7
@@
The following are some guidelines for use of Doxygen in the DPDK API documentati
* @param devargs
* A pointer to a strings array describing the new device
* to be attached. The strings should be a pci address like
* @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`.
+ * `0000:01:00.0` or **virtual** device name like `
net
_pcap0`.
* @param port_id
* A pointer to a port identifier actually attached.
*
* @param port_id
* A pointer to a port identifier actually attached.
*
@@
-645,7
+642,7
@@
The following are some guidelines for use of Doxygen in the DPDK API documentati
* 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:
* 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.
* Use ``-`` instead of ``*`` for lists within the Doxygen comment since the latter can get confused with the comment delimiter.