Write sphinx rst docs.

docs/man/man1/cdist.rst

@@ -1,22 +1,22 @@
 cdist(1)
 ========
+Usable Configuration Management
+
 Nico Schottelius <nico-cdist--@--schottelius.org>
 
 
-NAME
-----
-cdist - Usable Configuration Management
-
-
 SYNOPSIS
 --------
-cdist [-h] [-d] [-v] [-V] {banner,config,shell} ...
 
-cdist banner [-h] [-d] [-v]
+::
 
-cdist config [-h] [-d] [-V] [-c CONF_DIR] [-i MANIFEST] [-p] [-s] host [host ...]
+    cdist [-h] [-d] [-v] [-V] {banner,config,shell} ...
 
-cdist shell [-h] [-d] [-v] [-s SHELL]
+    cdist banner [-h] [-d] [-v]
+
+    cdist config [-h] [-d] [-V] [-c CONF_DIR] [-i MANIFEST] [-p] [-s] host [host ...]
+
+    cdist shell [-h] [-d] [-v] [-s SHELL]
 
 
 DESCRIPTION
@@ -28,16 +28,20 @@ GENERAL
 -------
 All commands accept the following options:
 
--d, --debug::
+.. option:: -d, --debug
+
     Set log level to debug
 
--h, --help::
+.. option:: -h, --help
+
    Show the help screen
 
--v, --verbose::
+.. option:: -v, --verbose
+
     Set log level to info, be more verbose
 
--V, --version::
+.. option:: -V, --version
+
    Show version and exit
 
 
@@ -51,10 +55,12 @@ CONFIG
 ------
 Configure one or more hosts
 
--h, --help::
+.. option:: -h, --help
+
     Show the help screen
 
--c CONF_DIR, --conf-dir CONF_DIR::
+.. option:: -c CONF_DIR, --conf-dir CONF_DIR
+
     Add a configuration directory. Can be specified multiple times.
     If configuration directories contain conflicting types, explorers or
     manifests, then the last one found is used. Additionally this can also
@@ -63,19 +69,24 @@ Configure one or more hosts
     --conf-dir argument have higher precedence over those set through the
     environment variable.
 
--i MANIFEST, --initial-manifest MANIFEST::
+.. option:: -i MANIFEST, --initial-manifest MANIFEST
+
     Path to a cdist manifest or - to read from stdin
 
--p, --parallel::
+.. option:: -p, --parallel
+
     Operate on multiple hosts in parallel
 
--s, --sequential::
+.. option:: -s, --sequential
+
     Operate on multiple hosts sequentially
 
---remote-copy REMOTE_COPY::
+.. option:: --remote-copy REMOTE_COPY
+
     Command to use for remote copy (should behave like scp)
 
---remote-exec REMOTE_EXEC::
+.. option:: --remote-exec REMOTE_EXEC
+
     Command to use for remote execution (should behave like ssh)
 
 SHELL
@@ -85,79 +96,78 @@ to the types as commands. It can be thought as an
 "interactive manifest" environment. See below for example
 usage. Its primary use is for debugging type parameters.
 
--s/--shell::
+.. option:: -s/--shell
+
     Select shell to use, defaults to current shell
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# Configure ikq05.ethz.ch with debug enabled
-% cdist config -d ikq05.ethz.ch
+.. code-block:: sh
 
-# Configure hosts in parallel and use a different configuration directory
-% cdist config -c ~/p/cdist-nutzung \
-    -p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
+    # Configure ikq05.ethz.ch with debug enabled
+    % cdist config -d ikq05.ethz.ch
 
-# Use custom remote exec / copy commands
-% cdist config --remote-exec /path/to/my/remote/exec \
-    --remote-copy /path/to/my/remote/copy \
-    -p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
+    # Configure hosts in parallel and use a different configuration directory
+    % cdist config -c ~/p/cdist-nutzung \
+        -p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
 
-# Display banner
-cdist banner
+    # Use custom remote exec / copy commands
+    % cdist config --remote-exec /path/to/my/remote/exec \
+        --remote-copy /path/to/my/remote/copy \
+        -p ikq02.ethz.ch ikq03.ethz.ch ikq04.ethz.ch
 
-# Show help
-% cdist --help
+    # Display banner
+    cdist banner
 
-# Show Version
-% cdist --version
+    # Show help
+    % cdist --help
 
-# Enter a shell that has access to emulated types
-% cdist shell
-% __git
-usage: __git --source SOURCE [--state STATE] [--branch BRANCH]
-             [--group GROUP] [--owner OWNER] [--mode MODE] object_id
+    # Show Version
+    % cdist --version
 
-
---------------------------------------------------------------------------------
+    # Enter a shell that has access to emulated types
+    % cdist shell
+    % __git
+    usage: __git --source SOURCE [--state STATE] [--branch BRANCH]
+                 [--group GROUP] [--owner OWNER] [--mode MODE] object_id
 
 
 ENVIRONMENT
 -----------
-TMPDIR, TEMP, TMP::
+TMPDIR, TEMP, TMP
     Setup the base directory for the temporary directory.
     See http://docs.python.org/py3k/library/tempfile.html for
     more information. This is rather useful, if the standard
     directory used does not allow executables.
 
-CDIST_LOCAL_SHELL::
+CDIST_LOCAL_SHELL
     Selects shell for local script execution, defaults to /bin/sh
 
-CDIST_REMOTE_SHELL::
+CDIST_REMOTE_SHELL
     Selects shell for remote scirpt execution, defaults to /bin/sh
 
-CDIST_REMOTE_EXEC::
+CDIST_REMOTE_EXEC
     Use this command for remote execution (should behave like ssh)
 
-CDIST_REMOTE_COPY::
+CDIST_REMOTE_COPY
     Use this command for remote copy (should behave like scp)
 
 EXIT STATUS
 -----------
 The following exit values shall be returned:
 
-0::
+0
     Successful completion
-1::
+1
     One or more host configurations failed
 
 
 SEE ALSO
 --------
-- cdist(7)
-- cdist-reference(7)
+- `cdist-type(7) <../man7/cdist-type.html>`_
+- `cdist-reference(7) <../man7/cdist-reference.html>`_
 
 
 COPYING