X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=cddbd7bb84de0fd22ef695f751f1c49dfa4ff3fa;hb=f9ef083c6cfe1cf435360a2b9dfed019853b6ae0;hp=7c1eb410a1dd2ee3dd96d4c0a1294e417a237f85;hpb=c36a82f045ae362b76af4f2a53af10a2a4d2d20f;p=dpdk.git diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst index 7c1eb410a1..cddbd7bb84 100644 --- a/doc/guides/contributing/documentation.rst +++ b/doc/guides/contributing/documentation.rst @@ -1,4 +1,4 @@ -.. doc_guidelines: +.. _doc_guidelines: DPDK Documentation Guidelines ============================= @@ -142,7 +142,7 @@ The following dependencies must be installed to build the documentation: * 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. @@ -155,21 +155,22 @@ It can be installed as follows: 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). -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. - 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. - 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 `_. @@ -187,7 +188,7 @@ It can be installed as follows: sudo apt-get -y install inkscape # Red Hat/Fedora. - sudo yum -y install inkscape + sudo dnf -y install inkscape `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. - 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. - sudo yum -y install texlive-collection-latexextra \ - texlive-collection-fontsextra + sudo dnf -y install texlive-collection-latexextra Build commands @@ -284,33 +282,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:: - - 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. +* 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. - This would be rendered as follows: +* 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. - *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.* + Long literal command lines can be shown wrapped with backslashes. For + example:: - *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 --txqflags=0x0 --disable-hw-vlan --enable-lro \ + --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024 --txd=1024 Whitespace @@ -334,7 +320,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 =============== @@ -382,12 +368,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. @@ -460,8 +445,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,9 +462,9 @@ Images * The DPDK documentation contains some legacy images in PNG format. These will be converted to SVG in time. -* `Inkscape `_ is the recommended graphics editor for creating the 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. @@ -633,7 +618,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 - * `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. * @@ -645,7 +630,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: - 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.