X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=550d8dec281e5eab9360bc78145e1d20e100909b;hb=770fabcd36ec11d64544e86ed7d2dda9f5c64daf;hp=cb5ca0dc7b12aebfc143cbd554d224bc32cef08f;hpb=6bdae907647691fe2f380efcd281cc276fafb3d0;p=dpdk.git diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst index cb5ca0dc7b..550d8dec28 100644 --- a/doc/guides/contributing/documentation.rst +++ b/doc/guides/contributing/documentation.rst @@ -1,4 +1,7 @@ -.. doc_guidelines: +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 The DPDK contributors + +.. _doc_guidelines: DPDK Documentation Guidelines ============================= @@ -19,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 | |-- ... ... @@ -34,18 +36,17 @@ The main directories that contain files related to documentation are shown below |-- testpmd_app_ug |-- rel_notes |-- nics - |-- xen |-- ... -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. @@ -61,16 +62,27 @@ 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: + + * 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. - 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). * **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. @@ -131,7 +143,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,23 +156,25 @@ 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 + sudo dnf -y install python-pip + sudo pip install --upgrade sphinx + sudo pip install --upgrade sphinx_rtd_theme - # Or, on any system with Python installed. - sudo easy_install -U sphinx - -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:: @@ -176,7 +190,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 +199,23 @@ 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 texlive-lang-greek # Red Hat/Fedora, selective install. - sudo yum -y install texlive-collection-latexextra \ - texlive-collection-fontsextra + 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 @@ -273,33 +297,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. - - This would be rendered as follows: +* 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:: - -* 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 --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \ + --txd=1024 --rxd=1024 Whitespace @@ -323,7 +335,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 +383,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 +460,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 +477,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. @@ -585,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: @@ -617,24 +628,19 @@ 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 `eth_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: - 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. @@ -660,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.