From 7e57575f9e1ad0909750d116e9eabc15c1c77e2c Mon Sep 17 00:00:00 2001 From: Darko Poljak Date: Wed, 20 Jul 2016 08:16:58 +0200 Subject: [PATCH] Improve and fix reference doc and cdist man page. --- docs/src/cdist-reference.rst.sh | 59 +++++++++++++++++---------------- docs/src/man1/cdist.rst | 41 +++++++++++++---------- 2 files changed, 55 insertions(+), 45 deletions(-) diff --git a/docs/src/cdist-reference.rst.sh b/docs/src/cdist-reference.rst.sh index b168d781..06842450 100755 --- a/docs/src/cdist-reference.rst.sh +++ b/docs/src/cdist-reference.rst.sh @@ -56,19 +56,19 @@ cat << eof Paths ----- \$HOME/.cdist - The standard cdist configuration directory relative to your home directory - This is usually the place you want to store your site specific configuration + The standard cdist configuration directory relative to your home directory. + This is usually the place you want to store your site specific configuration. cdist/conf/ - The distribution configuration directory - This contains types and explorers to be used + The distribution configuration directory. + This contains types and explorers to be used. confdir Cdist will use all available configuration directories and create a temporary confdir containing links to the real configuration directories. This way it is possible to merge configuration directories. By default it consists of everything in \$HOME/.cdist and cdist/conf/. - For more details see cdist(1) + For more details see cdist(1). confdir/files/ Cdist does not care about this directory besides providing access to it. @@ -99,16 +99,16 @@ confdir/type// This directory is referenced by the variable __type (see below). confdir/type//man.rst - Manpage in reStructuredText format (required for inclusion into upstream) + Manpage in reStructuredText format (required for inclusion into upstream). confdir/type//manifest Used to generate additional objects from a type. confdir/type//gencode-local - Used to generate code to be executed on the source host + Used to generate code to be executed on the source host. confdir/type//gencode-remote - Used to generate code to be executed on the target host + Used to generate code to be executed on the target host. confdir/type//parameter/required Parameters required by type, \n separated list. @@ -184,7 +184,7 @@ files (for instance to store template results). changed This empty file exists in an object directory, if the object has - code to be executed (either remote or local) + code to be executed (either remote or local). stdin This file exists and contains data, if data was provided on stdin when the type was called. @@ -196,67 +196,70 @@ The following environment variables are exported by cdist: __explorer Directory that contains all global explorers. - Available for: initial manifest, explorer, type explorer, shell + Available for: initial manifest, explorer, type explorer, shell. __files Directory that contains content from the "files" subdirectories from the configuration directories. - Available for: initial manifest, type manifest, type gencode, shell + Available for: initial manifest, type manifest, type gencode, shell. __manifest Directory that contains the initial manifest. - Available for: initial manifest, type manifest, shell + Available for: initial manifest, type manifest, shell. __global Directory that contains generic output like explorer. - Available for: initial manifest, type manifest, type gencode, shell + Available for: initial manifest, type manifest, type gencode, shell. __messages_in File to read messages from. - Available for: initial manifest, type manifest, type gencode + Available for: initial manifest, type manifest, type gencode. __messages_out File to write messages. - Available for: initial manifest, type manifest, type gencode + Available for: initial manifest, type manifest, type gencode. __object Directory that contains the current object. - Available for: type manifest, type explorer, type gencode and code scripts + Available for: type manifest, type explorer, type gencode and code scripts. __object_id The type unique object id. - Available for: type manifest, type explorer, type gencode and code scripts + Available for: type manifest, type explorer, type gencode and code scripts. Note: The leading and the trailing "/" will always be stripped (caused by the filesystem database and ensured by the core). Note: Double slashes ("//") will not be fixed and result in an error. __object_name The full qualified name of the current object. - Available for: type manifest, type explorer, type gencode + Available for: type manifest, type explorer, type gencode. __target_host The host we are deploying to. - Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell + Available for: explorer, initial manifest, type explorer, type manifest, type gencode, shell. __type Path to the current type. - Available for: type manifest, type gencode + Available for: type manifest, type gencode. __type_explorer Directory that contains the type explorers. - Available for: type explorer + Available for: type explorer. Environment variables (for writing) ----------------------------------- The following environment variables influence the behaviour of cdist: require - Setup dependencies between objects (see \`cdist manifest \`_) + Setup dependencies between objects (see \`cdist manifest \`_). + +CDIST_PATH + Colon delimited list of config directories. CDIST_LOCAL_SHELL - Use this shell locally instead of /bin/sh to execute scripts + Use this shell locally instead of /bin/sh to execute scripts. CDIST_REMOTE_SHELL - Use this shell remotely instead of /bin/sh to execute scripts + Use this shell remotely instead of /bin/sh to execute scripts. CDIST_OVERRIDE - Allow overwriting type parameters (see \`cdist manifest \`_) + Allow overwriting type parameters (see \`cdist manifest \`_). CDIST_ORDER_DEPENDENCY - Create dependencies based on the execution order (see \`cdist manifest \`_) + Create dependencies based on the execution order (see \`cdist manifest \`_). CDIST_REMOTE_EXEC - Use this command for remote execution (should behave like ssh) + Use this command for remote execution (should behave like ssh). CDIST_REMOTE_COPY - Use this command for remote copy (should behave like scp) + Use this command for remote copy (should behave like scp). eof diff --git a/docs/src/man1/cdist.rst b/docs/src/man1/cdist.rst index 114b42fe..5a4873f7 100644 --- a/docs/src/man1/cdist.rst +++ b/docs/src/man1/cdist.rst @@ -23,7 +23,10 @@ SYNOPSIS DESCRIPTION ----------- cdist is the frontend executable to the cdist configuration management. -cdist supports different subcommands as explained below. +It supports different subcommands as explained below. + +It is written in Python so it requires :strong:`python`\ (1) to be installed. +It requires a minimal Python version 3.2. GENERAL ------- @@ -54,7 +57,7 @@ cdist posters - a must have for every office. CONFIG ------ -Configure one or more hosts +Configure one or more hosts. .. option:: -c CONF_DIR, --conf-dir CONF_DIR @@ -110,13 +113,9 @@ FILES ~/.cdist Your personal cdist config directory. If exists it will be automatically used. -${cdist_prefix}/cdist/conf - The distribution configuration directory. ${cdist_prefix} is - installation-dependent. If you install cdist using git it is - equal to your cloned directory. If you install it using python - pip then it is equal to - ${prefix}/lib/python/site-packages/cdist sub-directory - where ${prefix}, by default, is /usr/local (see :strong:`python`\ (1)). +cdist/conf + The distribution configuration directory. It contains official types and + explorers. This path is relative to cdist installation directory. EXAMPLES -------- @@ -162,26 +161,34 @@ TMPDIR, TEMP, TMP more information. This is rather useful, if the standard directory used does not allow executables. +CDIST_PATH + Colon delimited list of config directories. + CDIST_LOCAL_SHELL - Selects shell for local script execution, defaults to /bin/sh + Selects shell for local script execution, defaults to /bin/sh. CDIST_REMOTE_SHELL - Selects shell for remote scirpt execution, defaults to /bin/sh + Selects shell for remote scirpt execution, defaults to /bin/sh. + +CDIST_OVERRIDE + Allow overwriting type parameters. + +CDIST_ORDER_DEPENDENCY + Create dependencies based on the execution order. CDIST_REMOTE_EXEC - Use this command for remote execution (should behave like ssh) + Use this command for remote execution (should behave like ssh). CDIST_REMOTE_COPY - Use this command for remote copy (should behave like scp) + Use this command for remote copy (should behave like scp). EXIT STATUS ----------- The following exit values shall be returned: -0 - Successful completion -1 - One or more host configurations failed +0 Successful completion. + +1 One or more host configurations failed. AUTHORS