From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by dpdk.org (Postfix) with ESMTP id 2CB8611C5 for ; Thu, 2 Jul 2015 15:51:02 +0200 (CEST) Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by fmsmga103.fm.intel.com with ESMTP; 02 Jul 2015 06:51:00 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.15,393,1432623600"; d="scan'208";a="517814229" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by FMSMGA003.fm.intel.com with ESMTP; 02 Jul 2015 06:51:00 -0700 Received: from sivswdev02.ir.intel.com (sivswdev02.ir.intel.com [10.237.217.46]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id t62DoxRY018972; Thu, 2 Jul 2015 14:50:59 +0100 Received: from sivswdev02.ir.intel.com (localhost [127.0.0.1]) by sivswdev02.ir.intel.com with ESMTP id t62Dox6v017614; Thu, 2 Jul 2015 14:50:59 +0100 Received: (from jmcnam2x@localhost) by sivswdev02.ir.intel.com with id t62DoxwI017610; Thu, 2 Jul 2015 14:50:59 +0100 From: John McNamara To: dev@dpdk.org Date: Thu, 2 Jul 2015 14:50:52 +0100 Message-Id: <1435845053-17203-3-git-send-email-john.mcnamara@intel.com> X-Mailer: git-send-email 1.7.4.1 In-Reply-To: <1435845053-17203-1-git-send-email-john.mcnamara@intel.com> References: <1435845053-17203-1-git-send-email-john.mcnamara@intel.com> Subject: [dpdk-dev] [PATCH 2/3] doc: added guidelines on dpdk documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 02 Jul 2015 13:51:03 -0000 Added guidelines on the purpose and structure of the DPDK documentation, how to build it and guidelines for creating it. Also added guidelines on how to format and submit a documentation patch. Signed-off-by: John McNamara --- doc/guides/guidelines/documentation.rst | 1005 +++++++++++++++++++++++++++++++ doc/guides/guidelines/index.rst | 2 + 2 files changed, 1007 insertions(+) create mode 100644 doc/guides/guidelines/documentation.rst diff --git a/doc/guides/guidelines/documentation.rst b/doc/guides/guidelines/documentation.rst new file mode 100644 index 0000000..d3e5905 --- /dev/null +++ b/doc/guides/guidelines/documentation.rst @@ -0,0 +1,1005 @@ +g.. doc_guidelines: + +DPDK Documentation Guidelines +============================= + +This document outlines the guidelines for writing the DPDK Guides and API +documentation in RST and Doxygen format. + +It also explains the structure of the DPDK documentation and shows how to +build the Html and PDF versions of the documents. + +It also explains how to submit a patch to the documentation. + + +Structure of the Documentation +------------------------------ + +The DPDK source code repository contains input files to build the API +documentation and User Guides. + +The main directories that contain files related to documentation are shown +below:: + + lib + |-- librte_acl + |-- librte_cfgfile + |-- librte_cmdline + |-- librte_compat + |-- librte_eal + | |-- ... + ... + doc + |-- api + +-- guides + |-- freebsd_gsg + |-- linux_gsg + |-- prog_guide + |-- sample_app_ug + |-- guidelines + |-- testpmd_app_ug + |-- rel_notes + |-- nics + |-- xen + |-- ... + + +The API documentation is built from `Doxygen +`_ comments in the header files. These +files are mainly in the ``lib/lib_rte_*`` 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. + +These files are included in the ``doc/guides/`` directory. The output is +controlled by the ``doc/guides/conf.py`` file. + + +Role of the Documentation +------------------------- + +The following items outline the roles of the different parts of the +documentation and when they need to be updated or added to by the developer. + +* **Release Notes** + + 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. + + In general developers do not have to update the Release Notes apart from + adding ABI announcements. + +* **API documentation** + + The API documentation explains how to use the public DPDK functions. The + `API index page `_ shows the generated API + documentation as related groups of functions. + + The API documentation should be updated via Doxygen comments when new + functions are added. + +* **Getting Started Guides** + + The Getting Started Guides show how to install and configure DPDK and + how to run DPDK based applications on different OSes. + + A Getting Started Guide should be added when DPDK is ported to a new OS. The + guide for the Skeleton Forwarding app is a good starting reference. + +* **The Programmers Guide** + + The Programmers Guide explains how the API components of DPDK such as + the EAL, Memzone, Rings and the Hash Library work. It also explains how some + higher level functionality such as Packet Distributor, Packet Framework and + KNI work. It also shows the build system and explains how to add + applications. + + The Programmers Guide should be expanded when new functionality is added to + DPDK. + +* **App Guides** + + The app guides document the DPDK applications in the ``app`` directory such + as ``testpmd``. + + The app guides should be updated if functionality is changed or added. + +* **Sample App Guides** + + The sample app guides document the DPDK example applications in the examples + directory. Generally they demonstrate a major feature such as L2 or L3 + Forwarding, Multi Process or Power Management. They explain the purpose of + the sample application, how to run it and step through some of the code to + explain the major functionality. + + A new sample application should be accompanied by new sample app guide. + +* **Network Interface Controller Drivers** + + The NIC Drivers document explains the features of the individual Poll Mode + Drivers, such as software requirements, configuration and initialization. + + New documentation should be added for new Poll Mode Drivers. + +* **Guidelines** + + The guideline documents record the DPDK guidelines on coding, design, ABI + usage and documentation. + + These should be changed to clarify or improve guidelines. + + +Building the Documentation +-------------------------- + +Dependencies +~~~~~~~~~~~~ + + +The following dependencies must be installed to build the documentation: + +* Doxygen. + +* Sphinx. + +* TexLive. + +* Inkscape. + +`Doxygen`_ generates documentation from commented source code. It can be +installed as follows: + +.. code-block:: console + + # Ubuntu/Debian. + sudo apt-get -y install doxygen + + # Red Hat/Fedora. + sudo yum -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: + +.. code-block:: console + + # Ubuntu/Debian. + sudo apt-get -y install python-sphinx + + # Red Hat/Fedora. + sudo yum -y install python-sphinx + + # Or, on any system with Python installed. + sudo easy_install -U sphinx + +For further information on getting started with Sphinx see the `Sphinx +Tutorial `_. + +.. Note:: + + To get full support for Figure and Table numbering it is best to install + Sphinx 1.3.1 or later. + + +`Inkscape`_ is a vector based graphics program which is used to create SVG +images and also to convert SVG images to PDF images. It can be installed as +follows: + +.. code-block:: console + + # Ubuntu/Debian. + sudo apt-get -y install inkscape + + # Red Hat/Fedora. + sudo yum -y install inkscape + +`TexLive `_ is an installation package for +Tex/LaTeX. It is used to generate the PDF versions of the +documentation. Installation of all of the TeX components required by Sphinx +can be tricky. If possible it is best to install TexLive Full to ensure that +you have all the requirements. It can be installed as follows: + +.. code-block:: console + + # Ubuntu/Debian. + + sudo apt-get -y install texlive-full + + # Red Hat/Fedora, selective install. + sudo yum -y install texlive + sudo yum -y install texlive-latex + sudo yum -y install texlive-collection-latex + sudo yum -y install texlive-collection-latexrecommended + sudo yum -y install texlive-collection-latexextra + sudo yum -y install texlive-dejavu + + +Build commands +~~~~~~~~~~~~~~ + +The documentation is built using the standard DPDK build system. Some examples +are shown below: + +* Generate all the documentation targets:: + + make doc + +* Generate the Doxygen API documentation in Html:: + + 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:: + + build/doc + |-- html + | |-- api + | +-- guides + | + +-- pdf + +-- guides + + +.. Note:: + + 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 +------------------- + +Here are some guidelines in relation to the style of the documentation: + +* Document the obvious as well as the obscure since it won't always be obvious + to the reader. For example an instruction like "Set up 64 2MB Hugepages" is + better when followed by a sample commandline or a link to the appropriate + section of the documentation. + +* Use American English spellings throughout. This can be checked using the + ``aspell`` utility:: + + aspell --lang=en_US --check doc/guides/sample_app_ug/mydoc.rst + + +RST Guidelines +-------------- + +The RST (reStructuredText) format is a plain text markup format that can be +converted to Html, PDF or other formats. It is most closely associated with +Python but it can be used to document any language. It is used in DPDK to +document everything apart from the API. + +The Sphinx documentation contains a very useful `RST Primer +`_ which is a good place to learn +the minimal set of syntax required to format a document. + +The official `reStructuredText `_ +website contains the specification for the RST format and also examples of how +to use it. However, for most developers the RST Primer above is a better +resource. + +The most common guidelines for writing RST text are detailed in the +`Documenting Python `_ +guidelines. The additional guidelines below reiterate or expand upon those +guidelines. + + +Readability +~~~~~~~~~~~ + +The main RST guideline is that the RST text should be readable in text format. + +Even though RST is a markup format and the text will most often be read when +rendered to Html or PDF it is important to maintain readability of the raw +text. This makes is easier for developers to read in an editor or in a +terminal. + + +Line Length +~~~~~~~~~~~ + +The existing documentation contains different styles for long lines and +paragraphs. The following are recommendations for new text in order of +preference: + +* Wrap lines at 80 characters. This is the Python RST recommendation and adds + to readability of the raw text. + +* Use one sentence per line in a paragraph, i.e., put a newline character + after each period/full stop. + +* Use one line per paragraph. + + +Whitespace +~~~~~~~~~~ + +* Standard RST indentation is 3 spaces. Code can be indented 4 spaces, + especially if it is copied from source files. + +* No tabs. Convert tabs in embedded code to 4 or 8 spaces. + +* No trailing whitespace. + +* The most common existing style in the documentation is to have only 1 space + after a period/full stop. + +* Add 2 blank lines before each section header. + +* Add 1 blank line after each section header. + +* Add 1 blank line between each line of a list. + + +Section Headers +~~~~~~~~~~~~~~~ + +* Section headers should use the use the following underline formats:: + + Level 1 Heading + =============== + + + Level 2 Heading + --------------- + + + Level 3 Heading + ~~~~~~~~~~~~~~~ + + + Level 4 Heading + ^^^^^^^^^^^^^^^ + + +* Level 4 headings should be used sparingly. + +* The underlines should match the length of the text. + +* In general, the heading should be less than 80 characters. + +* As noted above: + + * Add 2 blank lines before each section header. + + * Add 1 blank line after each section header. + + +Lists +~~~~~ + +* Bullet lists should be formatted with a leading ``*`` as follows:: + + * Item one. + + * Item two is a longer line that is wrapped at 80 characters and then + indented to match the start of the first line. + + * One space character between the bullet and the text is preferred. + +* Numbered lists can be formatted with a leading number but the preference is + to use ``#.`` which will give automatic numbering. This is more convenient + when adding or removing items:: + + #. Item one. + + #. Item two is a longer line that is wrapped at 80 characters and then + indented to match the start of the e first line. + +* Definition lists can be written with or without a bullet:: + + * Item one. + + Some text about item one. + + * Item two. + + Some text about item two. + +* All lists, and sub-lists, must be separated from the preceding text by a + blank line. This is a syntax requirement. + +* All list items should be separated by a blank line for readability. + + +Code and Literal block sections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Inline text that is required to be rendered with a fixed width font should + be enclosed in backquotes like this: \`\`text\`\`, so that it appears like + this: ``text``. + +* Fixed width, literal blocks of texts should be indented at least 3 spaces + and prefixed with ``::`` like this:: + + Here is some fixed width text:: + + 0x0001 0x0001 0x00FF 0x00FF + +* It is also possible to specify an encoding for a literal block using the + ``.. code-block::`` directive so that syntax highlighting can be + applied. Examples of supported highlighting are:: + + .. code-block:: console + .. code-block:: c + .. code-block:: python + .. code-block:: diff + .. code-block:: none + + That can be applied as follows:: + + .. code-block:: c + + #include + + int main() { + + printf("Hello World\n"); + + return 0; + } + + Which would be rendered as: + + .. code-block:: c + + #include + + int main() { + + printf("Hello World\n"); + + return 0; + } + + +* The default encoding for a literal block using the simplified ``::`` + directive is ``none``. + +* Avoid lines longer than 80 character in literal blocks since they can exceed + the page width when converted to PDF documentation. If possible 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 \ + -- -i --nb-cores=2 --nb-ports=2 \ + --total-num-mbufs=2048 + + +Images +~~~~~~ + +* All images should be in SVG scalar graphics format. They should be true SVG + XML files and should not include binary formats embedded in a SVG wrapper. + +* 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. Use some of the older images in ``doc/guides/prog_guide/img/`` + as a template, for example ``mbuf1.svg`` or ``ring-enqueue.svg``. + +* The SVG images should include a copyright notice, as an XML comment. + +* Images in the documentation should be formatted as follows: + + * The image should be preceded by a label in the format + ``.. _figure_XXXX:`` with a leading underscore and where ``XXXX`` is a + unique descriptive name. + + * Images should be included using the ``.. figure::`` directive and the + file type should be set to ``*`` (not ``.svg``). This allows the format + of the image to be changed if required. + + * Images must have a caption as part of the ``.. figure::`` directive. + +* Here is an example of the previous three guidelines:: + + .. _figure_mempool: + + .. figure:: img/mempool.* + + A mempool in memory with its associated ring. + +.. _mock_label: + +* Images can then be linked to using the ``:numref:`` directive:: + + The mempool layout is shown in :numref:`figure_mempool`. + + This would be rendered as: *The mempool layout is shown in* :ref:`Fig 6.3 + `. + + **Note**: The ``:numref:`` directive requires Sphinx 1.3.1 or later. With + earlier versions it will still be rendered as a link but won't have an + automatically generated number. + +* The caption of the image can be generated, with a link, using the ``:ref:`` + directive:: + + :ref:`figure_mempool` + + This would be rendered as: *A mempool in memory with its associated ring.* + +Tables +~~~~~~ + +* RST tables should be used sparingly. They are hard to format and to edit, + they are often rendered incorrectly in PDF format, and the same information + can usually be shown just as clearly with a list. + +* Tables in the documentation should be formatted as follows: + + * The table should be preceded by a label in the format + ``.. _table_XXXX:`` with a leading underscore and where ``XXXX`` is a + unique descriptive name. + + * Tables should be included using the ``.. table::`` directive and must + have a caption. + +* Here is an example of the previous two guidelines:: + + .. _table_qos_pipes: + + .. table:: Sample configuration for QOS pipes. + + +----------+----------+----------+ + | Header 1 | Header 2 | Header 3 | + | | | | + +==========+==========+==========+ + | Text | Text | Text | + +----------+----------+----------+ + | ... | ... | ... | + +----------+----------+----------+ + +* Tables can be linked to using the ``:numref:`` and ``:ref:`` directives, as + shown in the previous section for images. For example:: + + The QOS configuration is shown in :numref:`table_qos_pipes`. + +* Tables should not include merged cells since they are not supported by the + PDF renderer. + + +.. _links: + +Hyperlinks +~~~~~~~~~~ + +* Links to external websites can be plain URLs. The following is rendered as + http://dpdk.org:: + + http://dpdk.org + +* They can contain alternative text. The following is rendered as + `Check out DPDK `_:: + + `Check out DPDK `_ + +* An internal link can be generated by placing labels in the document with the + format ``.. _label_name``. + +* The following links to the top of this section: :ref:`links`:: + + .. _links: + + Hyperlinks + ~~~~~~~~~~ + + * The following links to the top of this section: :ref:`links`: + +.. Note:: + + The label must have a leading underscore but the reference to it must omit + it. This is a frequent cause of errors and warnings. + +* The use of a label is preferred since it works across files and will still + work if the header text changes. + + +.. _doxygen_guidelines: + +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. + +The following are some guidelines for use of Doxygen in the DPDK API +documentation: + +* New libraries that are documented with Doxygen should be added to the + Doxygen configuration file: ``doc/api/doxy-api.conf``. It is only required + to add the directory that contains the files. It isn't necessary to + explicitly name each file since the configuration matches all ``rte_*.h`` + files in the directory. + +* Use proper capitalization and punctuation in the Doxygen comments since they + will become sentences in the documentation. This in particular applies to + single line comments, which is the case the is most often forgotten. + +* Use ``@`` style Doxygen commands instead of ``\`` style commands. + +* Add a general description of each library at the head of the main header + files: + + .. code-block:: c + + /** + * @file + * RTE Mempool. + * + * A memory pool is an allocator of fixed-size object. It is + * identified by its name, and uses a ring to store free objects. + * ... + */ + +* Document the purpose of a function, the parameters used and the return + value: + + .. 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. + * + * @return + * 0 on success and port_id is filled, negative on error. + */ + int rte_eth_dev_attach(const char *devargs, uint8_t *port_id); + +* 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``. + +* Use ``-`` instead of ``*`` for lists within the Doxygen comment since the + latter can get confused with the comment delimiter. + +* Add an empty line between the function description, the ``@params`` and + ``@return`` for readability. + +* Place the ``@params`` description on separate line and indent it by 2 + spaces. (It would be better to use no indentation since this is more common + and also because checkpatch complains about leading whitespace in + comments. However this is the convention used in the existing DPDK code.) + +* Documented functions can be linked to simply by adding ``()`` to the + function name: + + .. code-block:: c + + /** + * The functions exported by the application Ethernet API to setup + * a device designated by its port identifier must be invoked in + * the following order: + * - rte_eth_dev_configure() + * - rte_eth_tx_queue_setup() + * - rte_eth_rx_queue_setup() + * - rte_eth_dev_start() + */ + + 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. + +* 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. + + .. code-block:: c + + /** + * ... + * + * Some text that references mempools. + * + * @see eal_memzone.c + */ + +* Doxygen supports two types of comments for documenting variables, constants + and members: prefix and postfix: + + .. code-block:: c + + /** This is a prefix comment. */ + #define RTE_FOO_ERROR 0x023. + + #define RTE_BAR_ERROR 0x024. /**< This is a postfix comment. */ + +* Postfix comments are preferred for struct members and constants if they can + be documented in the same way: + + .. code-block:: c + + struct rte_eth_stats { + uint64_t ipackets; /**< Total number of received packets. */ + uint64_t opackets; /**< Total number of transmitted packets.*/ + uint64_t ibytes; /**< Total number of received bytes. */ + uint64_t obytes; /**< Total number of transmitted bytes. */ + uint64_t imissed; /**< Total of RX missed packets. */ + uint64_t ibadcrc; /**< Total of RX packets with CRC error. */ + uint64_t ibadlen; /**< Total of RX packets with bad length. */ + } + + Note: postfix comments should be aligned with spaces not tabs in accordance + with the :ref:`coding_style`. + +* If a single comment type can't be used, due to line length limitations then + prefix comments should be preferred. For example this section of the code + contains prefix comments, postfix comments on the same line and postfix + comments on a separate line: + + .. code-block:: c + + /** Number of elements in the elt_pa array. */ + uint32_t pg_num __rte_cache_aligned; + uint32_t pg_shift; /**< LOG2 of the physical pages. */ + uintptr_t pg_mask; /**< Physical page mask value. */ + uintptr_t elt_va_start; + /**< Virtual address of the first mempool object. */ + uintptr_t elt_va_end; + /**< Virtual address of the mempool object. */ + phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT]; + /**< Array of physical page addresses for the mempool buffer. */ + + This doesn't have an effect on the rendered documentation but it is + confusing for the developer reading the code. It this case it would be + clearer to use prefix comments throughout: + + .. code-block:: c + + /** Number of elements in the elt_pa array. */ + uint32_t pg_num __rte_cache_aligned; + /** LOG2 of the physical pages. */ + uint32_t pg_shift; + /** Physical page mask value. */ + uintptr_t pg_mask; + /** Virtual address of the first mempool object. */ + uintptr_t elt_va_start; + /** Virtual address of the mempool object. */ + uintptr_t elt_va_end; + /** 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 | grep "warning:" + +* Read the rendered section of the documentation that you have added for + correctness, clarity and consistency with the surrounding text. + + +Patching the Documentation +-------------------------- + +One of the easiest ways to contribute to DPDK is to submit a patch to the +documentation. + +Over time the documentation may contain information that is slightly out of +date or that could be improved upon. Newcomers to the DPDK project often +notice these issues as they work through the examples and how-to guides. + +Rather than emailing the development list, or even ignoring the issue, it is +just as easy to submit a patch to fix it. The following instructions explain +how to do that and since they are meant to encourage contributions they assume +no development experience or prior exposure to the DPDK workflow. + +#. Install the documentation dependencies as shown above. As a minimum you + should install Sphinx:: + + # Ubuntu/Debian. + sudo apt-get -y install python-sphinx + + # Red Hat/Fedora. + sudo yum -y install python-sphinx + + If you are going to patch the API docs you will need Doxygen. You can omit + TexLive and Inkscape for now. + +#. Install ``git`` as follows:: + + # Ubuntu/Debian. + sudo apt-get -y install git + + # Red Hat/Fedora. + sudo yum -y install git + + If you have any problems, refer to the official `Git installation guide + `_. + +#. Configure your ``.gitconfig`` file with your name and email address:: + + git config --global user.name "J. Smith" + git config --global user.email jsmith@example.com + + If you wish you can also configure the default editor that is used to write + commit messages:: + + git config --global core.editor vi + + See the `Git getting started guide + `_ if + you have any issues. + +#. Clone the DPDK repository (this can take a minute or two):: + + git clone http://dpdk.org/git/dpdk + +#. Change into the new ``dpdk`` directory and test if you have the required + dependencies to build the docs:: + + cd dpdk + make doc-guides-html + + If you get warnings about missing utilities go back and work through + installing the dependencies again. + + If you installed some of the other dependencies you can try the following, + but they aren't required:: + + # If you installed Doxygen: + make doc-api-html + + # If you installed Inkscape and TexLive as well: + make doc + + .. Note:: + + You can ignore a warning about upgrading Sphinx, that is optional. If + you are building the documentation on Mac OS you can ignore a warning + from ``sed``. + +#. Using your preferred editor make the changes to the file you want to fix or + improve. For example:: + + vi doc/guides/linux_gsg/quick_start.rst + +#. Once you have make the modifications you should see a change in the ``git + status``:: + + git status + + On branch master + Your branch is up-to-date with 'origin/master'. + Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes) + + modified: doc/guides/linux_gsg/quick_start.rst + + +#. You will be able to review your changes using ``git diff``: + + .. code-block:: diff + + git diff + + diff --git a/quick_start.rst b/quick_start.rst + index b07fc87..7b49e1c 100644 + --- a/doc/guides/linux_gsg/quick_start.rst + +++ b/doc/guides/linux_gsg/quick_start.rst + @@ -256,7 +256,7 @@ The following selection demonstrates the launch + + Enter hex bitmask of cores to execute test app on + Example: to execute app on cores 0 to 7, enter 0xff + - bitmaks: 0x01 + + bitmask: 0x01 + Launching app + EAL: coremask set to 1 + EAL: Detected lcore 0 on socket 0 + + Two other diff options that are useful when dealing with changes to + documentation are word and character diffs:: + + # View differences by word instead of lines: + git diff --color-words + + # View differences by character: + git diff --color-words=. + + +#. Rebuild the docs and fix any new warnings:: + + make doc-guides-html + +#. Open the output Html document and review your changes in the context of the + surrounding text. Use a Web browser like the following:: + + firefox build/doc/html/guides/linux_gsg/quick_start.html & + +#. If everything is okay you can commit your changes to your local repository + and generate a patch. The first step is to add the file(s) that you + modified:: + + git add doc/guides/linux_gsg/quick_start.rst + +#. Now commit the changes to the local repository. You must "sign" the commit + by using ``-s``. This will insert the name and email address that you + configured in your ``.gitconfig`` above:: + + git commit -s + + This will drop you into the default, or configured, editor and you can + insert a message like the following:: + + doc: fix minor typo in linux getting started guide + + Fixed a minor typo in the Linux Getting Started Guide. + + Signed-off-by: J. Smith + + The first line will be used as a subject line for an email so it should: + + * start with ``doc:`` + * be less than 50 characters + * be lowercase only + * and not end with a period/full stop + + The body of the text should: + + * describe the change + * be wrapped at 72 characters + * have proper punctuation and capitalization + + The body of the message should generally be longer than the example above + and should explain the purpose of the change. + +#. You can now create and email a patch. This can be done in one step from git + but for beginners it is best done in two steps so that you can review the + patch. First generate the patch:: + + git format-patch -1 + + This will generate a patch like the following:: + + 0001-doc-fix-minor-typo-in-linux-getting-started-guide.patch + + If you have a large patch or set of patches you can also generate a cover + letter to explain the changes by adding the ``--cover-letter`` option. + + +#. If you are happy that everything looks good you can sent the patch to the + DPDK ``dev`` mailing list:: + + git send-mail --to dev@dpdk.org 0001-doc-fix-minor-typo-etc.patch + + If you have issues see the `git send-mail + `_ section of the the Git + documentation. + + If all goes well the patch will appear on the `DPDK dev mailing list + `_ and in the `DPDK Patchwork + `_. diff --git a/doc/guides/guidelines/index.rst b/doc/guides/guidelines/index.rst index bfb9fa3..1050d99 100644 --- a/doc/guides/guidelines/index.rst +++ b/doc/guides/guidelines/index.rst @@ -8,3 +8,5 @@ Guidelines coding_style design versioning + documentation + -- 1.8.1.4