X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=170dacdb77765a1baff2276f2ac07c2f4e8cb92a;hb=3004d3454192515f44fa4df1c4f64c9cde687913;hp=cb5ca0dc7b12aebfc143cbd554d224bc32cef08f;hpb=6bdae907647691fe2f380efcd281cc276fafb3d0;p=dpdk.git diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst index cb5ca0dc7b..170dacdb77 100644 --- a/doc/guides/contributing/documentation.rst +++ b/doc/guides/contributing/documentation.rst @@ -1,4 +1,4 @@ -.. doc_guidelines: +.. _doc_guidelines: DPDK Documentation Guidelines ============================= @@ -34,7 +34,6 @@ The main directories that contain files related to documentation are shown below |-- testpmd_app_ug |-- rel_notes |-- nics - |-- xen |-- ... @@ -63,9 +62,20 @@ added to by the developer. any known issues. The Releases Notes also contain notifications of features that will change ABI compatibility in the next major release. - Developers should update the Release Notes to add a short description of new or updated features. - Developers should also update the Release Notes to add ABI announcements if necessary, - (see :doc:`/contributing/versioning` for details). + Developers should include updates to the Release Notes with patch sets that relate to any of the following sections: + + * New Features + * Resolved Issues (see below) + * Known Issues + * API Changes + * ABI Changes + * Shared Library Versions + + Resolved Issues should only include issues from previous releases that have been resolved in the current release. + Issues that are introduced and then fixed within a release cycle do not have to be included here. + + Refer to the Release Notes from the previous DPDK release for the correct format of each section. + * **API documentation** @@ -131,7 +141,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. @@ -144,21 +154,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 `_. @@ -176,7 +187,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. @@ -185,13 +196,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 @@ -273,33 +281,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:: +* 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. - 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. +* 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. - This is a new paragraph, since it is separated from the - previous paragraph by a blank line. + Long literal command lines can be shown wrapped with backslashes. For + example:: - This would be rendered as follows: - - *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.* - - -* 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 @@ -323,7 +319,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 =============== @@ -371,12 +367,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. @@ -449,8 +444,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 @@ -466,9 +461,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. @@ -622,7 +617,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. * @@ -634,7 +629,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.