doc: Add man page section to documentation guide

We also replace 'reST' with the far more common 'rST'.

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>

1 files changed, 76 insertions, 8 deletions

diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst
index 9fe473ce8..0ba5e544f 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
 -------------