@@ -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
-------------
We also replace 'reST' with the far more common 'rST'. Signed-off-by: Stephen Finucane <stephen@that.guru> --- .../internals/contributing/documentation-style.rst | 84 +++++++++++++++++++--- 1 file changed, 76 insertions(+), 8 deletions(-)