From: Stephen Finucane <[email protected]> We also replace 'reST' with the far more common 'rST'.
Signed-off-by: Stephen Finucane <[email protected]> Signed-off-by: Ben Pfaff <[email protected]> --- .../internals/contributing/documentation-style.rst | 84 +++++++++++++++++++--- 1 file changed, 76 insertions(+), 8 deletions(-) diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index 9fe473ce8114..0ba5e544f14e 100644 --- a/Documentation/internals/contributing/documentation-style.rst +++ b/Documentation/internals/contributing/documentation-style.rst @@ -41,17 +41,17 @@ documents found in the project tree. reStructuredText vs. Sphinx --------------------------- -`reStructuredText (reST)`__ is the syntax, while `Sphinx`__ is a documentation -generator. Sphinx introduces a number of extensions to reST, like the -``:ref:`` role, which can and should be used in documentation, but these will -not work correctly on GitHub. As such, these extensions should not be used in -any documentation in the root level, such as the ``README``. +`reStructuredText (rST)`__ is the syntax, while `Sphinx`__ is a documentation +generator. Sphinx introduces a number of extensions to rST, like the ``:ref:`` +role, which can and should be used in documentation, but these will not work +correctly on GitHub. As such, these extensions should not be used in any +documentation in the root level, such as the ``README``. __ http://docutils.sourceforge.net/rst.html __ http://www.sphinx-doc.org/ -reST Conventions ----------------- +rST Conventions +--------------- Basics ~~~~~~ @@ -59,7 +59,7 @@ Basics Many of the basic documentation guidelines match those of the :doc:`coding-style`. -- Use reStructuredText (reST) for all documentation. +- Use reStructuredText (rST) for all documentation. Sphinx extensions can be used, but only for documentation in the ``Documentation`` folder. @@ -90,6 +90,12 @@ File Names - Use hyphens as space delimiters. For example: ``my-readme-document.rst`` + .. note:: + + An exception to this rule is any man pages, which take an trailing number + corresponding to the number of arguments required. This number is preceded + by an underscore. + - Use lowercase filenames. .. note:: @@ -285,6 +291,68 @@ Comments .. TODO(stephenfin) This section needs some work. This TODO will not appear in the final generated document, however. +Man Pages +--------- + +In addition to the above, man pages have some specific requirements: + +- You **must** define the following sections: + + - Synopsis + + - Description + + - Options + + Note that `NAME` is not included - this is automatically generated by Sphinx + and should not be manually defined. Also note that these do not need to be + uppercase - Sphinx will do this automatically. + + Additional sections are allowed. Refer to `man-pages(8)` for information on + the sections generally allowed. + +- You **must not** define a `NAME` section. + + See above. + +- The `OPTIONS` section must describe arguments and options using the + `program`__ and `option`__ directives. + + This ensures the output is formatted correctly and that you can + cross-reference various programs and commands from the documentation. For + example:: + + .. program:: ovs-do-something + + .. option:: -f, --force + + Force the operation + + .. option:: -b <bridge>, --bridge <bridge> + + Name or ID of bridge + + .. important:: + + Option argument names should be enclosed in angle brackets, as above. + +- Any references to the application or any other Open vSwitch application must + be marked up using the `program` role. + + This allows for easy linking in the HTML output and correct formatting in the + man page output. For example:: + + To do something, run :program:`ovs-do-something`. + +- The man page must be included in the list of man page documents found in + `conf.py`__ + +Refer to existing man pages for worked examples. + +__ http://www.sphinx-doc.org/en/stable/domains.html#directive-program +__ http://www.sphinx-doc.org/en/stable/domains.html#directive-option +__ http://www.sphinx-doc.org/en/stable/config.html#confval-man_pages + Writing Style ------------- -- 2.10.2 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
