d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: show how to include code in guides

Browse Source 
Currently the documentation describes how to add code snippets to the
docs using code blocks. This can be problematic as the code snippets
in the docs may fall out of sync with the actual code it is referencing
within DPDK. This patch adds instructions to the contribution guide
about how to include code in the docs using literalinclude which will
dynamically get the code from source when the docs are generated. This
will help to ensure that the code within the docs is up to date and not
out of sync with the actual code.

Signed-off-by: Conor Walsh <conor.walsh@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: David Marchand <david.marchand@redhat.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
This commit is contained in:
Conor Walsh 2021-05-06 16:40:59 +00:00 committed by Thomas Monjalon
parent 0d025f019c
commit 413c75c33c
1 changed files with 56 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/guides/contributing/documentation.rst
View File

@ -381,6 +381,62 @@ Code and Literal block sections
return 0;
}
* Code snippets can also be included directly from the code using the ``literalinclude`` block.
Using this block instead of a code block will ensure that the code snippets
shown in the documentation are always up to date with the code.
The following will include a snippet from the skeleton sample app::
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
:language: c
:start-after: Display the port MAC address.
:end-before: Enable RX in promiscuous mode for the Ethernet device.
:dedent: 1
This would be rendered as:
.. literalinclude:: ../../../examples/skeleton/basicfwd.c
:language: c
:start-after: Display the port MAC address.
:end-before: Enable RX in promiscuous mode for the Ethernet device.
:dedent: 1
Specifying ``:language:`` will enable syntax highlighting for the specified language.
``:dedent:`` is used in this example to remove 1 leading tab from each line of the snippet.
* ``start-after`` and ``end-before`` can use any text within a given file,
however it may be difficult to find unique text within your code to mark the
start and end of your snippets. In these cases, it is recommended to include
explicit tags in your code to denote these locations for documentation purposes.
The accepted format for these comments is:
* Before the code snippet, create a new comment which is a sentence explaining
what the code snippet contains. The comment is terminated with a scissors ``8<``.
* After the code snippet, create another new comment which starts with a
scissors ``>8``, then ``End of`` and the first comment repeated.
* The scissors should be orientated as shown to make it clear what code is being snipped.
This can be done as follows:
.. code-block:: c
/* Example feature being documented. 8< */
foo(bar);
/* >8 End of example feature being documented. */
``foo(bar);`` could then be included in the docs using::
.. literalinclude:: ../../../examples/sample_app/main.c
:language: c
:start-after: Example feature being documented. 8<
:end-before: >8 End of example feature being documented.
If a multiline comment is needed before the snippet,
then the last line of the multiline comment should be in the same format as
the first comment shown in the example.
* More information about the ``literalinclude`` block can be found within the
`Sphinx Documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=literalinclude#directive-literalinclude>`_.
* The default encoding for a literal block using the simplified ``::``
directive is ``none``.