Write sphinx rst docs.

.gitignore

@@ -20,6 +20,9 @@ MANIFEST
 dist/
 cdist/version.py
 
+#sphinx build dir
+_build/
+
 # Packaging: Archlinux
 /PKGBUILD
 /cdist-*.pkg.tar.xz

Makefile

@@ -18,15 +18,6 @@
 #
 #
 
-A2XM=a2x -f manpage --no-xmllint -a encoding=UTF-8
-A2XH=a2x -f xhtml --no-xmllint -a encoding=UTF-8
-# Create cross-links in html man pages
-# We look for something like "cdist-type(7)" and make a href out of it
-# The first matching group is the man page name and the second group
-# is the man page section (1 or 7). The first three lines of the input
-# (xml, DOCTYPE, head tags) are ignored, since the head tags contains
-# the title of the page and should not contain a href.
-CROSSLINK=sed -i '' '1,3!s/\([[:alnum:]_-]*\)(\([17]\))/<a href="..\/man\2\/\1.html">&<\/a>/g'
 helper=./bin/build-helper
 
 MANDIR=docs/man
@@ -45,6 +36,8 @@ CHANGELOG_FILE=docs/changelog
 
 PYTHON_VERSION=cdist/version.py
 
+SPHINXM=make -C $(MANDIR) man
+SPHINXH=make -C $(MANDIR) html
 ################################################################################
 # Manpages
 #
@@ -52,59 +45,42 @@ MAN1DSTDIR=$(MANDIR)/man1
 MAN7DSTDIR=$(MANDIR)/man7
 
 # Manpages #1: Types
-# Use shell / ls to get complete list - $(TYPEDIR)/*/man.text does not work
-MANTYPESRC=$(shell ls $(TYPEDIR)/*/man.text)
-
-# replace first path component
+# Use shell / ls to get complete list - $(TYPEDIR)/*/man.rst does not work
+MANTYPESRC=$(shell ls $(TYPEDIR)/*/man.rst)
 MANTYPEPREFIX=$(subst $(TYPEDIR)/,$(MAN7DSTDIR)/cdist-type,$(MANTYPESRC))
+MANTYPES=$(subst /man.rst,.rst,$(MANTYPEPREFIX))
 
-# replace man.text with .7 or .html
-MANTYPEMAN=$(subst /man.text,.7,$(MANTYPEPREFIX))
-MANTYPEHTML=$(subst /man.text,.html,$(MANTYPEPREFIX))
-MANTYPEALL=$(MANTYPEMAN) $(MANTYPEHTML)
-
-# Link manpage so A2XH does not create man.html but correct named file
-$(MAN7DSTDIR)/cdist-type%.text: $(TYPEDIR)/%/man.text
+# Link manpage: do not create man.html but correct named file
+$(MAN7DSTDIR)/cdist-type%.rst: $(TYPEDIR)/%/man.rst
 	ln -sf "../../../$^" $@
 
 # Manpages #2: reference
-MANREF=$(MAN7DSTDIR)/cdist-reference.text
-MANREFSH=$(MANDIR)/cdist-reference.text.sh
-MANREFMAN=$(MANREF:.text=.7)
-MANREFHTML=$(MANREF:.text=.html)
-MANREFALL=$(MANREFMAN) $(MANREFHTML)
+MANREF=$(MAN7DSTDIR)/cdist-reference.rst
+MANREFSH=$(MANDIR)/cdist-reference.rst.sh
 
 $(MANREF): $(MANREFSH)
 	$(MANREFSH)
 
-# Manpages #3: static pages
-MAN1STATIC=$(shell ls $(MAN1DSTDIR)/*.text)
-MAN7STATIC=$(shell ls $(MAN7DSTDIR)/*.text)
-MANSTATICMAN=$(MAN1STATIC:.text=.1) $(MAN7STATIC:.text=.7)
-MANSTATICHTML=$(MAN1STATIC:.text=.html) $(MAN7STATIC:.text=.html)
-MANSTATICALL=$(MANSTATICMAN) $(MANSTATICHTML)
-
-# Manpages #4: generic part
+# Manpages #3: generic part
+mansphinxman: $(MANTYPES) $(MANREF)
+	$(SPHINXM)
 
-# Creating the type manpage
-%.1 %.7: %.text
-	$(A2XM) $^
+mansphinxhtml: $(MANTYPES) $(MANREF)
+	$(SPHINXH)
 
-# Creating the type html page
-%.html: %.text
-	$(A2XH) $^
-	$(CROSSLINK) $@
-
-man: $(MANTYPEALL) $(MANREFALL) $(MANSTATICALL)
+man: mansphinxman mansphinxhtml
 
 # Manpages #5: release part
 MANWEBDIR=$(WEBBASE)/man/$(CHANGELOG_VERSION)
+MANBUILDDIR=$(MANDIR)/_build/html
 
-man-dist: man check-date
+man-dist: man
 	rm -rf "${MANWEBDIR}"
-	mkdir -p "${MANWEBDIR}/man1" "${MANWEBDIR}/man7"
-	cp ${MAN1DSTDIR}/*.html ${MAN1DSTDIR}/*.css ${MANWEBDIR}/man1
-	cp ${MAN7DSTDIR}/*.html ${MAN7DSTDIR}/*.css ${MANWEBDIR}/man7
+	mkdir -p "${MANWEBDIR}"
+	# mkdir -p "${MANWEBDIR}/man1" "${MANWEBDIR}/man7"
+	# cp ${MAN1DSTDIR}/*.html ${MAN1DSTDIR}/*.css ${MANWEBDIR}/man1
+	# cp ${MAN7DSTDIR}/*.html ${MAN7DSTDIR}/*.css ${MANWEBDIR}/man7
+	cp -R ${MANBUILDDIR}/* ${MANWEBDIR}
 	cd ${MANWEBDIR} && git add . && git commit -m "cdist manpages update: $(CHANGELOG_VERSION)" || true
 
 man-latest-link: web-pub
@@ -216,15 +192,13 @@ release:
 #
 
 clean:
-	rm -f $(MAN7DSTDIR)/cdist-reference.text
+	rm -f $(MAN7DSTDIR)/cdist-reference.rst
 
 	find "$(MANDIR)" -mindepth 2 -type l \
-	    -o -name "*.1" \
-	    -o -name "*.7" \
-	    -o -name "*.html" \
-	    -o -name "*.xml" \
 	| xargs rm -f
 
+	make -C $(MANDIR) clean
+
 	find * -name __pycache__  | xargs rm -rf
 
 	# Archlinux

cdist/conf/type/__apt_key/man.rst

@@ -1,11 +1,8 @@
 cdist-type__apt_key(7)
 ======================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manage the list of keys used by apt
 
-NAME
-----
-cdist-type__apt_key - manage the list of keys used by apt
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -20,13 +17,13 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-state::
+state
    'present' or 'absent'. Defaults to 'present'
 
-keyid::
+keyid
    the id of the key to add. Defaults to __object_id
 
-keyserver::
+keyserver
    the keyserver from which to fetch the key. If omitted the default set in
    ./parameter/default/keyserver is used.
 
@@ -34,25 +31,25 @@ keyserver::
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# Add Ubuntu Archive Automatic Signing Key
-__apt_key 437D05B5
-# Same thing
-__apt_key 437D05B5 --state present
-# Get rid of it
-__apt_key 437D05B5 --state absent
+.. code-block:: sh
+
+    # Add Ubuntu Archive Automatic Signing Key
+    __apt_key 437D05B5
+    # Same thing
+    __apt_key 437D05B5 --state present
+    # Get rid of it
+    __apt_key 437D05B5 --state absent
 
-# same thing with human readable name and explicit keyid
-__apt_key UbuntuArchiveKey --keyid 437D05B5
+    # same thing with human readable name and explicit keyid
+    __apt_key UbuntuArchiveKey --keyid 437D05B5
 
-# same thing with other keyserver
-__apt_key UbuntuArchiveKey --keyid 437D05B5 --keyserver keyserver.ubuntu.com
---------------------------------------------------------------------------------
+    # same thing with other keyserver
+    __apt_key UbuntuArchiveKey --keyid 437D05B5 --keyserver keyserver.ubuntu.com
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__apt_key_uri/man.rst

@@ -1,11 +1,8 @@
 cdist-type__apt_key_uri(7)
 ==========================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Add apt key from uri
 
-NAME
-----
-cdist-type__apt_key_uri - add apt key from uri
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -15,16 +12,16 @@ Download a key from an uri and add it to the apt keyring.
 
 REQUIRED PARAMETERS
 -------------------
-uri::
+uri
    the uri from which to download the key
 
 
 OPTIONAL PARAMETERS
 -------------------
-state::
+state
    'present' or 'absent', defaults to 'present'
 
-name::
+name
    a name for this key, used when testing if it is already installed.
    Defaults to __object_id
 
@@ -32,17 +29,17 @@ name::
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__apt_key_uri rabbitmq \
-   --name 'RabbitMQ Release Signing Key <info@rabbitmq.com>' \
-   --uri http://www.rabbitmq.com/rabbitmq-signing-key-public.asc \
-   --state present
---------------------------------------------------------------------------------
+.. code-block:: sh
+
+    __apt_key_uri rabbitmq \
+       --name 'RabbitMQ Release Signing Key <info@rabbitmq.com>' \
+       --uri http://www.rabbitmq.com/rabbitmq-signing-key-public.asc \
+       --state present
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__apt_norecommends/man.rst

@@ -1,11 +1,8 @@
 cdist-type__apt_norecommends(7)
 ===============================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Configure apt to not install recommended packages
 
-NAME
-----
-cdist-type__apt_norecommends - configure apt to not install recommended packages
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -26,14 +23,14 @@ None.
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__apt_norecommends
---------------------------------------------------------------------------------
+.. code-block:: sh
+
+    __apt_norecommends
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__apt_ppa/man.rst

@@ -1,11 +1,8 @@
 cdist-type__apt_ppa(7)
 ======================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manage ppa repositories
 
-NAME
-----
-cdist-type__apt_ppa - Manage ppa repositories
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -15,7 +12,7 @@ This cdist type allows manage ubuntu ppa repositories.
 
 REQUIRED PARAMETERS
 -------------------
-state::
+state
    The state the ppa should be in, either 'present' or 'absent'.
    Defaults to 'present'
 
@@ -28,20 +25,20 @@ None.
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# Enable a ppa repository
-__apt_ppa ppa:sans-intern/missing-bits
-# same as
-__apt_ppa ppa:sans-intern/missing-bits --state present
+.. code-block:: sh
+
+    # Enable a ppa repository
+    __apt_ppa ppa:sans-intern/missing-bits
+    # same as
+    __apt_ppa ppa:sans-intern/missing-bits --state present
 
-# Disable a ppa repository
-__apt_ppa ppa:sans-intern/missing-bits --state absent
---------------------------------------------------------------------------------
+    # Disable a ppa repository
+    __apt_ppa ppa:sans-intern/missing-bits --state absent
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__apt_source/man.rst

@@ -1,11 +1,8 @@
 cdist-type__apt_source(7)
 =========================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manage apt sources
 
-NAME
-----
-cdist-type__apt_source - manage apt sources
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -15,52 +12,52 @@ This cdist type allows you to manage apt sources.
 
 REQUIRED PARAMETERS
 -------------------
-uri::
+uri
    the uri to the apt repository
 
 
 OPTIONAL PARAMETERS
 -------------------
-arch::
+arch
    set this if you need to force and specific arch (ubuntu specific)
 
-state::
+state
    'present' or 'absent', defaults to 'present'
 
-distribution::
+distribution
    the distribution codename to use. Defaults to DISTRIB_CODENAME from
    the targets /etc/lsb-release
 
-component::
+component
    space delimited list of components to enable. Defaults to an empty string.
 
 
 BOOLEAN PARAMETERS
 ------------------
-include-src::
+include-src
    include deb-src entries
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__apt_source rabbitmq \
-   --uri http://www.rabbitmq.com/debian/ \
-   --distribution testing \
-   --component main \
-   --include-src \
-   --state present
+.. code-block:: sh
+
+    __apt_source rabbitmq \
+       --uri http://www.rabbitmq.com/debian/ \
+       --distribution testing \
+       --component main \
+       --include-src \
+       --state present
 
-__apt_source canonical_partner \
-   --uri http://archive.canonical.com/ \
-   --component partner --state present
---------------------------------------------------------------------------------
+    __apt_source canonical_partner \
+       --uri http://archive.canonical.com/ \
+       --component partner --state present
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__apt_update_index/man.rst

@@ -1,11 +1,8 @@
 cdist-type__apt_update_index(7)
 ===============================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Update apt's package index
 
-NAME
-----
-cdist-type__apt_update_index - Update apt's package index
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -25,14 +22,14 @@ None.
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__apt_update_index
---------------------------------------------------------------------------------
+.. code-block:: sh
+
+    __apt_update_index
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__block/man.rst

@@ -1,11 +1,8 @@
 cdist-type__block(7)
 ====================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manage blocks of text in files
 
-NAME
-----
-cdist-type__block - Manage blocks of text in files
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -18,62 +15,62 @@ of text.
 
 REQUIRED PARAMETERS
 -------------------
-text::
+text
    the text to manage.
    If text is '-' (dash), take what was written to stdin as the text.
 
 
 OPTIONAL PARAMETERS
 -------------------
-file::
+file
    the file in which to manage the text block.
    Defaults to object_id.
 
-prefix::
+prefix
    the prefix to add before the text.
    Defaults to #cdist:__block/$__object_id
 
-suffix::
+suffix
    the suffix to add after the text.
    Defaults to #/cdist:__block/$__object_id
 
-state::
+state
    'present' or 'absent', defaults to 'present'
 
 
 MESSAGES
 --------
-add::
+add
    block was added
-update::
+update
    block was updated/changed
-remove::
+remove
    block was removed
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# text from argument
-__block /path/to/file \
-   --prefix '#start' \
-   --suffix '#end' \
-   --text 'some\nblock of\ntext'
+.. code-block:: sh
+
+    # text from argument
+    __block /path/to/file \
+       --prefix '#start' \
+       --suffix '#end' \
+       --text 'some\nblock of\ntext'
 
-# text from stdin
-__block some-id \
-   --file /path/to/file \
-   --text - << DONE
-here some block
-of text
-DONE
---------------------------------------------------------------------------------
+    # text from stdin
+    __block some-id \
+       --file /path/to/file \
+       --text - << DONE
+    here some block
+    of text
+    DONE
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__ccollect_source/man.rst

@@ -1,59 +1,58 @@
 cdist-type__ccollect_source(7)
 ==============================
-Nico Schottelius <nico-cdist--@--schottelius.org>
-
+Manage ccollect sources
 
-NAME
-----
-cdist-type__ccollect_source - Manage ccollect sources
+Nico Schottelius <nico-cdist--@--schottelius.org>
 
 
 DESCRIPTION
 -----------
 This cdist type allows you to create or delete ccollect sources.
 
+
 REQUIRED PARAMETERS
 -------------------
-source::
+source
     The source from which to backup
-destination::
+destination
     The destination directory
 
 
 OPTIONAL PARAMETERS
 -------------------
-state::
+state
     'present' or 'absent', defaults to 'present'
-ccollectconf::
+ccollectconf
     The CCOLLECT_CONF directory. Defaults to /etc/ccollect.
 
 
 OPTIONAL MULTIPLE PARAMETERS
 ----------------------------
-exclude::
+exclude
     Paths to exclude of backup
 
+
 BOOLEAN PARAMETERS
 ------------------
-verbose::
+verbose
     Whether to report backup verbosely
 
+
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__ccollect_source doc.ungleich.ch \
-    --source doc.ungleich.ch:/ \
-    --destination /backup/doc.ungleich.ch \
-    --exclude '/proc/*' --exclude '/sys/*' \
-    --verbose
+.. code-block:: sh
 
---------------------------------------------------------------------------------
+    __ccollect_source doc.ungleich.ch \
+        --source doc.ungleich.ch:/ \
+        --destination /backup/doc.ungleich.ch \
+        --exclude '/proc/*' --exclude '/sys/*' \
+        --verbose
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 - ccollect(1)
 - http://www.nico.schottelius.org/software/ccollect/
 

cdist/conf/type/__cdist/man.rst

@@ -1,11 +1,8 @@
 cdist-type__cdist(7)
 ====================
-Nico Schottelius <nico-cdist--@--schottelius.org>
-
+Manage cdist installations
 
-NAME
-----
-cdist-type__cdist - Manage cdist installations
+Nico Schottelius <nico-cdist--@--schottelius.org>
 
 
 DESCRIPTION
@@ -26,16 +23,16 @@ REQUIRED PARAMETERS
 
 OPTIONAL PARAMETERS
 -------------------
-username::
+username
     Select the user to create for the cdist installation.
     Defaults to "cdist".
 
-source::
+source
     Select the source from which to clone cdist from.
     Defaults to "git://github.com/telmich/cdist.git".
 
 
-branch::
+branch
     Select the branch to checkout from.
     Defaults to "master".
 
@@ -43,18 +40,18 @@ branch::
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# Install cdist for user cdist in her home as subfolder cdist
-__cdist /home/cdist/cdist
+.. code-block:: sh
+
+    # Install cdist for user cdist in her home as subfolder cdist
+    __cdist /home/cdist/cdist
 
-# Use alternative source
-__cdist --source "git://git.schottelius.org/cdist" /home/cdist/cdist
---------------------------------------------------------------------------------
+    # Use alternative source
+    __cdist --source "git://git.schottelius.org/cdist" /home/cdist/cdist
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__cdistmarker/man.rst

@@ -1,11 +1,8 @@
 cdist-type__cdistmarker(7)
 ==========================
-Daniel Maher <phrawzty+cdist--@--gmail.com>
-
+Add a timestamped cdist marker.
 
-NAME
-----
-cdist-type__cdistmarker - Add a timestamped cdist marker.
+Daniel Maher <phrawzty+cdist--@--gmail.com>
 
 
 DESCRIPTION
@@ -23,11 +20,11 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-destination::
+destination
     The path and filename of the marker.
     Default: /etc/cdist-configured
 
-format::
+format
     The format of the timestamp. This is passed directly to system 'date'.
     Default: -u
 
@@ -35,18 +32,18 @@ format::
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# Creates the marker as normal.
-__cdistmarker
+.. code-block:: sh
+
+    # Creates the marker as normal.
+    __cdistmarker
 
-# Creates the marker differently.
-__cdistmarker --destination /tmp/cdist_marker --format '+%s'
---------------------------------------------------------------------------------
+    # Creates the marker differently.
+    __cdistmarker --destination /tmp/cdist_marker --format '+%s'
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdisty-type.html>`_
 
 
 COPYING

cdist/conf/type/__config_file/man.rst

@@ -1,11 +1,8 @@
 cdist-type__config_file(7)
 ==========================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manages config files
 
-NAME
-----
-cdist-type__config_file - manages config files
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -21,37 +18,37 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-group::
+group
    see cdist-type__file
-mode::
+mode
    see cdist-type__file
-onchange::
+onchange
    the code to run if the file changes
-owner::
+owner
    see cdist-type__file
-source::
+source
    Path to the config file.
    If source is '-' (dash), take what was written to stdin as the config file content.
-state::
+state
    see cdist-type__file
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__config_file /etc/consul/conf.d/watch_foo.json \
-   --owner root --group consul --mode 640 \
-   --source "$__type/files/watch_foo.json" \
-   --state present \
-   --onchange 'service consul status >/dev/null && service consul reload || true'
---------------------------------------------------------------------------------
+.. code-block:: sh
+
+    __config_file /etc/consul/conf.d/watch_foo.json \
+       --owner root --group consul --mode 640 \
+       --source "$__type/files/watch_foo.json" \
+       --state present \
+       --onchange 'service consul status >/dev/null && service consul reload || true'
 
 
 SEE ALSO
 --------
-- cdist-type(7)
-- cdist-type__file(7)
+- `cdist-type(7) <cdist-type.html>`_
+- `cdist-type__file(7) <cdist-type__file.html>`_
 
 
 COPYING

cdist/conf/type/__consul/man.rst

@@ -1,11 +1,8 @@
 cdist-type__consul(7)
 =====================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Install consul
 
-NAME
-----
-cdist-type__consul - install consul
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -22,10 +19,10 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-state::
+state
    either 'present' or 'absent'. Defaults to 'present'
 
-version::
+version
    which version of consul to install. See ./files/versions for a list of
    supported versions. Defaults to the latest known version.
 
@@ -33,19 +30,19 @@ version::
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# just install using defaults
-__consul
+.. code-block:: sh
+
+    # just install using defaults
+    __consul
 
-# specific version
-__consul \
-   --version 0.4.1
---------------------------------------------------------------------------------
+    # specific version
+    __consul \
+       --version 0.4.1
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__consul_agent/man.rst

@@ -1,11 +1,8 @@
 cdist-type__consul_agent(7)
 ===========================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manage the consul agent
 
-NAME
-----
-cdist-type__consul_agent - manage the consul agent
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -20,129 +17,154 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-acl-datacenter::
+acl-datacenter
    only used by servers. This designates the datacenter which is authoritative
    for ACL information.
-acl-default-policy::
+
+acl-default-policy
    either "allow" or "deny"; defaults to "allow". The default policy controls the
    behavior of a token when there is no matching rule.
-acl-down-policy::
+
+acl-down-policy
    either "allow", "deny" or "extend-cache"; "extend-cache" is the default.
-acl-master-token::
+
+acl-master-token
    only used for servers in the acl_datacenter. This token will be created with
    management-level permissions if it does not exist. It allows operators to
    bootstrap the ACL system with a token ID that is well-known.
-acl-token::
+
+acl-token
    when provided, the agent will use this token when making requests to the
    Consul servers.
-acl-ttl::
+
+acl-ttl
    used to control Time-To-Live caching of ACLs.
-bind-addr::
+
+bind-addr
    sets the bind address for cluster communication
-bootstrap-expect::
+
+bootstrap-expect
    sets server to expect bootstrap mode
-ca-file-source::
+
+ca-file-source
    path to a PEM encoded certificate authority file which will be uploaded and
    configure using the ca_file config option.
-cert-file-source::
+
+cert-file-source
    path to a PEM encoded certificate file which will be uploaded and
    configure using the cert_file config option.
-client-addr::
+
+client-addr
    sets the address to bind for client access
-datacenter::
+
+datacenter
    datacenter of the agent
-encrypt::
+
+encrypt
    provides the gossip encryption key
-group::
+
+group
    the primary group for the agent
-json-config::
+
+json-config
    path to a partial json config file without leading { and trailing }.
    If json-config is '-' (dash), take what was written to stdin as the file content.
-key-file-source::
+
+key-file-source
    path to a PEM encoded private key file which will be uploaded and
    configure using the key_file config option.
-node-name::
+
+node-name
    name of this node. Must be unique in the cluster
-retry-join::
+
+retry-join
    address to attempt joining every retry_interval until at least one join works.
    Can be specified multiple times.
-user::
+
+user
    the user to run the agent as
-state::
+
+state
    if the agent is 'present' or 'absent'. Defaults to 'present'.
    Currently state=absent is not working due to some dependency issues.
 
 
 BOOLEAN PARAMETERS
 ------------------
-disable-remote-exec::
+disable-remote-exec
    disables support for remote execution. When set to true, the agent will ignore any incoming remote exec requests.
-disable-update-check::
+
+disable-update-check
    disables automatic checking for security bulletins and new version releases
-leave-on-terminate::
+
+leave-on-terminate
    gracefully leave cluster on SIGTERM
-rejoin-after-leave::
+
+rejoin-after-leave
    rejoin the cluster using the previous state after leaving
-server::
+
+server
    used to control if an agent is in server or client mode
-syslog::
+
+syslog
    enables logging to syslog
-verify-incoming::
+
+verify-incoming
    enforce the use of TLS and verify a client's authenticity on incomming connections
-verify-outgoing::
+
+verify-outgoing
    enforce the use of TLS and verify the peers authenticity on outgoing connections
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-# configure as server, bootstrap and rejoin
-hostname="$(cat "$__global/explorer/hostname")"
-__consul_agent \
-   --datacenter dc1 \
-   --node-name "${hostname%%.*}" \
-   --disable-update-check \
-   --server \
-   --rejoin-after-leave \
-   --bootstrap-expect 3 \
-   --retry-join consul-01 \
-   --retry-join consul-02 \
-   --retry-join consul-03
-
-# configure as server, bootstrap and rejoin with ssl support
-hostname="$(cat "$__global/explorer/hostname")"
-__consul_agent \
-   --datacenter dc1 \
-   --node-name "${hostname%%.*}" \
-   --disable-update-check \
-   --server \
-   --rejoin-after-leave \
-   --bootstrap-expect 3 \
-   --retry-join consul-01 \
-   --retry-join consul-02 \
-   --retry-join consul-03 \
-   --ca-file-source /path/to/ca.pem \
-   --cert-file-source /path/to/cert.pem \
-   --key-file-source /path/to/key.pem \
-   --verify-incoming \
-   --verify-outgoing
-
-# configure as client and try joining existing cluster
-__consul_agent \
-   --datacenter dc1 \
-   --node-name "${hostname%%.*}" \
-   --disable-update-check \
-   --retry-join consul-01 \
-   --retry-join consul-02 \
-   --retry-join consul-03
-
---------------------------------------------------------------------------------
+.. code-block:: sh
+
+    # configure as server, bootstrap and rejoin
+    hostname="$(cat "$__global/explorer/hostname")"
+    __consul_agent \
+       --datacenter dc1 \
+       --node-name "${hostname%%.*}" \
+       --disable-update-check \
+       --server \
+       --rejoin-after-leave \
+       --bootstrap-expect 3 \
+       --retry-join consul-01 \
+       --retry-join consul-02 \
+       --retry-join consul-03
+
+    # configure as server, bootstrap and rejoin with ssl support
+    hostname="$(cat "$__global/explorer/hostname")"
+    __consul_agent \
+       --datacenter dc1 \
+       --node-name "${hostname%%.*}" \
+       --disable-update-check \
+       --server \
+       --rejoin-after-leave \
+       --bootstrap-expect 3 \
+       --retry-join consul-01 \
+       --retry-join consul-02 \
+       --retry-join consul-03 \
+       --ca-file-source /path/to/ca.pem \
+       --cert-file-source /path/to/cert.pem \
+       --key-file-source /path/to/key.pem \
+       --verify-incoming \
+       --verify-outgoing
+
+    # configure as client and try joining existing cluster
+    __consul_agent \
+       --datacenter dc1 \
+       --node-name "${hostname%%.*}" \
+       --disable-update-check \
+       --retry-join consul-01 \
+       --retry-join consul-02 \
+       --retry-join consul-03
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 - http://www.consul.io/docs/agent/options.html
 
 

cdist/conf/type/__consul_check/man.rst

@@ -1,11 +1,8 @@
 cdist-type__consul_check(7)
 =============================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manages consul checks
 
-NAME
-----
-cdist-type__consul_check - manages consul checks
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -23,43 +20,49 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-interval::
+interval
    the interval in which the script given with --script should be run
-script::
+
+script
    the shell command to run every --interval
-ttl::
+
+ttl
    how long a check is considered healthy without being updated through the
    HTTP interfave
-id::
+
+id
    Defaults to --name
-name::
+
+name
    The name of this check. Defaults to __object_id
-notes::
+
+notes
    human readable description
-state::
+
+state
    if this check is 'present' or 'absent'. Defaults to 'present'.
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__consul_check redis \
-   --script /usr/local/bin/check_redis.py \
-   --interval 10s
+.. code-block:: sh
+
+    __consul_check redis \
+       --script /usr/local/bin/check_redis.py \
+       --interval 10s
 
-__consul_check some-object-id \
-   --id web-app \
-   --name "Web App Status" \
-   --notes "Web app does a curl internally every 10 seconds" \
-   --ttl 30s
---------------------------------------------------------------------------------
+    __consul_check some-object-id \
+       --id web-app \
+       --name "Web App Status" \
+       --notes "Web app does a curl internally every 10 seconds" \
+       --ttl 30s
 
 
 SEE ALSO
 --------
-- cdist-type(7)
-- cdist-type__consul_agent(7)
+- `cdist-type(7) <cdist-type.html>`_
+- `cdist-type__consul_agent(7) <cdist-type__consul_agent.html>`_
 
 
 COPYING

cdist/conf/type/__consul_reload/man.rst

@@ -1,11 +1,8 @@
 cdist-type__consul_reload(7)
 ============================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Reload consul
 
-NAME
-----
-cdist-type__consul_reload - reload consul
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -26,14 +23,14 @@ None.
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__consul_reload
---------------------------------------------------------------------------------
+.. code-block:: sh
+
+    __consul_reload
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 
 
 COPYING

cdist/conf/type/__consul_service/man.rst

@@ -1,11 +1,8 @@
 cdist-type__consul_service(7)
 =============================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manages consul services
 
-NAME
-----
-cdist-type__consul_service - manages consul services
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -23,46 +20,53 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-check-interval::
+check-interval
    the interval in which the script given with --check-script should be run
-check-script::
+
+check-script
    the shell command to run every --check-interval
-check-ttl::
+
+check-ttl
    how long a service is considered healthy without being updated through the
    HTTP interfave
-id::
+
+id
    Defaults to --name
-name::
+
+name
    The name of this service. Defaults to __object_id
-port::
+
+port
    the port at which this service can be reached
-state::
+
+state
    if this service is 'present' or 'absent'. Defaults to 'present'.
-tag::
+
+tag
    a tag to add to this service. Can be specified multiple times.
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__consul_service redis \
-   --tag master \
-   --tag production \
-   --port 8000 \
-   --check-script /usr/local/bin/check_redis.py \
-   --check-interval 10s
+.. code-block:: sh
+
+    __consul_service redis \
+       --tag master \
+       --tag production \
+       --port 8000 \
+       --check-script /usr/local/bin/check_redis.py \
+       --check-interval 10s
 
-__consul_service webapp \
-   --port 80 \
-   --check-ttl 10s
---------------------------------------------------------------------------------
+    __consul_service webapp \
+       --port 80 \
+       --check-ttl 10s
 
 
 SEE ALSO
 --------
-- cdist-type(7)
-- cdist-type__consul_agent(7)
+- `cdist-type(7) <cdist-type.html>`_
+- `cdist-type__consul_agent(7) <cdist-type__consul_agent.html>`_
 
 
 COPYING

cdist/conf/type/__consul_template/man.rst

@@ -1,11 +1,8 @@
 cdist-type__consul_template(7)
 ==============================
-Steven Armstrong <steven-cdist--@--armstrong.cc>
-
+Manage the consul-template service
 
-NAME
-----
-cdist-type__consul_template - manage the consul-template service
+Steven Armstrong <steven-cdist--@--armstrong.cc>
 
 
 DESCRIPTION
@@ -24,52 +21,69 @@ None.
 
 OPTIONAL PARAMETERS
 -------------------
-auth-username::
+auth-username
    specify a username for basic authentication.
-auth-password::
+
+auth-password
    specify a password for basic authentication.
-batch-size::
+
+batch-size
    the size of the batch when polling multiple dependencies.
-consul::
+
+consul
    the location of the Consul instance to query (may be an IP address or FQDN) with port.
    Defaults to 'localhost:8500'.
-log-level::
+
+log-level
    The log level for output. This applies to the stdout/stderr logging as well
    as syslog logging (if enabled). Valid values are "debug", "info", "warn",
    and "err". The default value is "warn".
-max-stale::
+
+max-stale
    the maximum staleness of a query. If specified, Consul will distribute work among all
    servers instead of just the leader.
-retry::
+
+retry
    the amount of time to wait if Consul returns an error when communicating
    with the API.
-state::
+
+state
    either 'present' or 'absent'. Defaults to 'present'
-ssl-cert::
+
+ssl-cert
    Path to an SSL client certificate to use to authenticate to the consul server.
    Useful if the consul server "verify_incoming" option is set.
-ssl-ca-cert::
+
+ssl-ca-cert
    Path to a CA certificate file, containing one or more CA certificates to
    use to validate the certificate sent by the consul server to us. This is a
    handy alternative to setting --ssl-no-verify if you are using your own CA.
-syslog-facility::
+
+syslog-facility
    The facility to use when sending to syslog. This requires the use of --syslog.
    The default value is LOCAL0.
-token::
+
+token
    the Consul API token.
-vault-address::
+
+vault-address
    the location of the Vault instance to query (may be an IP address or FQDN) with port.
-vault-token::
+
+vault-token
    the Vault API token.
-vault-ssl-cert::
+
+vault-ssl-cert
    Path to an SSL client certificate to use to authenticate to the vault server.
-vault-ssl-ca-cert::
+
+vault-ssl-ca-cert
    Path to a CA certificate file, containing one or more CA certificates to
    use to validate the certificate sent by the vault server to us.
-version::
+
+version
    which version of consul-template to install. See ./files/versions for a list of
    supported versions. Defaults to the latest known version.
-wait::
+
+wait
    the minimum(:maximum) to wait before rendering a new template to disk and
    triggering a command, separated by a colon (:). If the optional maximum
    value is omitted, it is assumed to be 4x the required minimum value.
@@ -77,36 +91,40 @@ wait::
 
 BOOLEAN PARAMETERS
 ------------------
-ssl::
+ssl
    use HTTPS while talking to Consul. Requires the Consul server to be configured to serve secure connections.
-ssl-no-verify::
+
+ssl-no-verify
    ignore certificate warnings. Only used if ssl is enabled.
-syslog::
+
+syslog
    Send log output to syslog (in addition to stdout and stderr).
-vault-ssl::
+
+vault-ssl
    use HTTPS while talking to Vault. Requires the Vault server to be configured to serve secure connections.
-vault-ssl-no-verify::
+
+vault-ssl-no-verify
    ignore certificate warnings. Only used if vault is enabled.
 
 
 EXAMPLES
 --------
 
---------------------------------------------------------------------------------
-__consul_template \
-   --consul consul.service.consul:8500 \
-   --retry 30s
+.. code-block:: sh
+
+    __consul_template \
+       --consul consul.service.consul:8500 \
+       --retry 30s
 
-# specific version
-__consul_template \
-   --version 0.6.5 \
-   --retry 30s
---------------------------------------------------------------------------------
+    # specific version
+    __consul_template \
+       --version 0.6.5 \
+       --retry 30s
 
 
 SEE ALSO
 --------
-- cdist-type(7)
+- `cdist-type(7) <cdist-type.html>`_
 - https://github.com/hashicorp/consul-template
 
 

cdist/conf/type/__consul_template_template/man.rst

@@ -1,11 +1,8 @@
 cdist-type__consul_template_template(7)