docs: describe the basic RST structure for a man page

Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/docs/styleguide.rst b/docs/styleguide.rst
index 71f29320cb8f60d269366802be39ae76501690ac..2998e90963da941fec4cf14136e69000f2473830 100644 (file)
--- a/docs/styleguide.rst
+++ b/docs/styleguide.rst
@@ -64,3 +64,89 @@ which allows for 6 levels of headings
 
    Heading 6
    ^^^^^^^^^
+
+Manual pages
+============
+
+RST documents created as manual pages must have the following structure
+
+::
+
+  ===========
+  ::PROGRAM::
+  ===========
+
+  ---------------------------
+  ...line line description...
+  ---------------------------
+
+  :Manual section: 8
+  :Manual group: Virtualization Support
+
+  .. contents::
+
+  SYNOPSIS
+  ========
+
+  ``::PROGRAM::`` [*OPTION*]...
+
+  DESCRIPTION
+  ===========
+
+  ...describe the tool / program ...
+
+  OPTIONS
+  =======
+
+  ``-h``, ``--help``
+
+  Display command line help usage then exit.
+
+  ...and other args....
+
+  FILES
+  =====
+
+  ...any files used that the user needs to know about. eg config
+  files in particular...
+
+  AUTHORS
+  =======
+
+  Please refer to the AUTHORS file distributed with libvirt.
+
+  BUGS
+  ====
+
+  Please report all bugs you discover.  This should be done via either:
+
+  #. the mailing list
+
+   `https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_
+
+  #. the bug tracker
+
+   `https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_
+
+  Alternatively, you may report bugs to your software distributor / vendor.
+
+
+  COPYRIGHT
+  =========
+
+  Copyright (C) ::DATE:: ::ORIGINAL AUTHOR::, and the authors listed in the
+  libvirt AUTHORS file.
+
+  LICENSE
+  =======
+
+  ``::PROGRAM::`` is distributed under the terms of the GNU LGPL v2.1+.
+  This is free software; see the source for copying conditions. There
+  is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+  PURPOSE
+
+  SEE ALSO
+  ========
+
+  ...other man page links....
+  `https://www.libvirt.org/ <https://www.libvirt.org/>`_