@@ -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``.
@@ -59,7 +59,7 @@ Basics
Many of the basic documentation guidelines match those of the
-- Use reStructuredText (reST) for all documentation.
+- Use reStructuredText (rST) for all documentation.
Sphinx extensions can be used, but only for documentation in the
@@ -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.
@@ -285,6 +291,68 @@ Comments
.. TODO(stephenfin) This section needs some work. This TODO will not
appear in the final generated document, however.
+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
+ .. 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
+Refer to existing man pages for worked examples.