From 22f242b1d99fb14241dc6942a693a723ca18ef54 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Tue, 17 Jan 2012 23:53:58 +0100 Subject: [PATCH] huge documentation cleanup Signed-off-by: Nico Schottelius --- doc/dev/todo/niconext | 22 ++++++---------------- doc/man/cdist-reference.text.sh | 8 ++++---- doc/man/man1/cdist.text | 2 +- doc/man/man7/cdist-explorer.text | 4 ++-- doc/man/man7/cdist-hacker.text | 8 +++++--- doc/man/man7/cdist-stages.text | 25 +++++-------------------- doc/man/man7/cdist-tutorial.text | 16 ---------------- 7 files changed, 23 insertions(+), 62 deletions(-) diff --git a/doc/dev/todo/niconext b/doc/dev/todo/niconext index e1c19869..0d1b53bb 100644 --- a/doc/dev/todo/niconext +++ b/doc/dev/todo/niconext @@ -1,23 +1,13 @@ -- write tutorial - - containing many links?! - - cdist-manifest - - cdist-type - - ... - - cdist-hacker - - - remove cdist(7) reference everywhere - - check cross links - - check other docs: - - cdist-best-practice.text - - cdist-explorer.text - cdist-hacker.text - - cdist-manifest.text - - cdist-reference.text - cdist-stages.text - - cdist-type.text - 51 -> ssh stuff double: cdist-best-practice and here +- release 2.0.5 +- cdist-cache:: + How to get use information about the hosts we have been working on [advanced] +cdist-scaling-tuning:: + How to scale out with cdist and which tunings to apply. [advanced] + -------------------------------------------------------------------------------- diff --git a/doc/man/cdist-reference.text.sh b/doc/man/cdist-reference.text.sh index a1757c43..6b4e786f 100755 --- a/doc/man/cdist-reference.text.sh +++ b/doc/man/cdist-reference.text.sh @@ -1,6 +1,6 @@ #!/bin/sh # -# 2010-2011 Nico Schottelius (nico-cdist at schottelius.org) +# 2010-2012 Nico Schottelius (nico-cdist at schottelius.org) # # This file is part of cdist. # @@ -74,7 +74,7 @@ conf/manifest/init:: conf/manifest/*:: All other files in this directory are not directly used by cdist, but you can seperate configuration mappings, if you have a lot of code in the - manifest/init file. This may also be very helpful to have different admins + manifest/init file. This may also be helpful to have different admins maintain different groups of hosts. conf/explorer/:: @@ -90,7 +90,7 @@ conf/type//:: This directory is referenced by the variable __type (see below). conf/type//man.text:: - Manpage in Asciidoc format (nequired for inclusion into upstream) + Manpage in Asciidoc format (required for inclusion into upstream) conf/type//manifest:: Used to generate additional objects from a type. @@ -199,7 +199,7 @@ __type_explorer:: SEE ALSO -------- -- cdist(7) +- cdist(1) COPYING diff --git a/doc/man/man1/cdist.text b/doc/man/man1/cdist.text index 03948036..99c28f8b 100644 --- a/doc/man/man1/cdist.text +++ b/doc/man/man1/cdist.text @@ -99,5 +99,5 @@ SEE ALSO COPYING ------- -Copyright \(C) 2011 Nico Schottelius. Free use of this software is +Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/man7/cdist-explorer.text b/doc/man/man7/cdist-explorer.text index b9c342a9..2c25d845 100644 --- a/doc/man/man7/cdist-explorer.text +++ b/doc/man/man7/cdist-explorer.text @@ -39,7 +39,7 @@ A very simple explorer may look like this: hostname -------------------------------------------------------------------------------- -Which is in practise the "hostname" explorer. +Which is in practise the ***hostname*** explorer. A type explorer, which could check for the status of a package may look like this: @@ -64,5 +64,5 @@ SEE ALSO COPYING ------- -Copyright \(C) 2010-2011 Nico Schottelius. Free use of this software is +Copyright \(C) 2010-2012 Nico Schottelius. Free use of this software is granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/man7/cdist-hacker.text b/doc/man/man7/cdist-hacker.text index f8e3730e..9bdf63d4 100644 --- a/doc/man/man7/cdist-hacker.text +++ b/doc/man/man7/cdist-hacker.text @@ -23,7 +23,7 @@ REPORTING BUGS -------------- If you believe you've found a bug and verified that it is in the latest version, drop a mail to the cdist mailing list, -subject prefixed with "[BUG] ". +subject prefixed with "[BUG] " or create an issue on github. CODING CONVENTIONS (EVERYWHERE) @@ -31,6 +31,8 @@ CODING CONVENTIONS (EVERYWHERE) If something should be better done or needs to fixed, add the word FIXME nearby, so grepping for FIXME gives all positions that need to be fixed. +Indention is 4 spaces (welcome to the python world). + HOW TO SUBMIT STUFF FOR INCLUSION INTO UPSTREAM CDIST ----------------------------------------------------- @@ -47,7 +49,7 @@ work nor kill the authors brain: - Code to be included should be branched of the upstream "master" branch - Exception: Bugfixes to a version branch - On a merge request, always name the branch I should pull from -- Always ensure **all** manpages build: ./build.sh man +- Always ensure **all** manpages build. Use **./build man** to test. - If you developed more than **one** feature, consider submitting them in seperate branches. This way one feature can already be included, even if the other needs to be improved. @@ -73,5 +75,5 @@ SEE ALSO COPYING ------- -Copyright \(C) 2011 Nico Schottelius. Free use of this software is +Copyright \(C) 2011-2012 Nico Schottelius. Free use of this software is granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/man7/cdist-stages.text b/doc/man/man7/cdist-stages.text index 8ac30015..c1b73a8d 100644 --- a/doc/man/man7/cdist-stages.text +++ b/doc/man/man7/cdist-stages.text @@ -9,20 +9,8 @@ cdist-stages - Stages used during configuration deployment DESCRIPTION ----------- -Starting the execution of deployment with cdist-deploy-to(1), cdist passes -through different stages, each can be triggered and debugged on its own. -Reading the source of the cdist-deploy-to executable shows the scripts -responsible for each stage. - - -STAGE 0: INTERNAL PREPERATION ------------------------------ -Before running the user facing stages, cdist prepares the target host -to contain cdist binaries and creates a clean environment for the -configuration run. - -Related documentation: - - Source of cdist-deploy-to +Starting the execution of deployment with cdist, cdist passes +through different stages. STAGE 1: TARGET INFORMATION RETRIEVAL @@ -45,7 +33,7 @@ be created. STAGE 3: OBJECT INFORMATION RETRIEVAL ------------------------------------- Every object is checked whether its type has explorers and if so, these are -transfered to the target host and executed. The results are transfered back +executed on the target host. The results are transfered back and can be used in the following stages to decide what changes need to be made on the target to implement the desired state. @@ -86,19 +74,16 @@ The cache stores the information from the current run for later use. SUMMARY ------- If, and only if, all the stages complete without an errors, the configuration -will be applied to the target. Each stage can also be run individually, though -dependencies for each stage must be fulfilled and thus the stages must be run -in correct order. +will be applied to the target. SEE ALSO -------- - cdist(1) -- cdist(7) - cdist-reference(7) COPYING ------- -Copyright \(C) 2010-2011 Nico Schottelius, Steven Armstrong. Free use of this software is +Copyright \(C) 2010-2012 Nico Schottelius, Steven Armstrong. Free use of this software is granted under the terms of the GNU General Public License version 3 (GPLv3). diff --git a/doc/man/man7/cdist-tutorial.text b/doc/man/man7/cdist-tutorial.text index 2bc703ce..85419025 100644 --- a/doc/man/man7/cdist-tutorial.text +++ b/doc/man/man7/cdist-tutorial.text @@ -37,20 +37,6 @@ cdist-reference:: cdist-explorer:: Interested in getting more information about the target system? [intermediate] -cdist-cache:: - How to get use information about the hosts we have been working on [advanced] - -cdist-scaling-tuning:: - How to scale out with cdist and which tunings to apply. [advanced] - - TUNING CDIST - ------------ - - - speedup processing with ControlMaster option of - ssh - => different document - - cdist-stages:: Understand the internal workflow of cdist. [advanced] @@ -58,8 +44,6 @@ cdist-hacker:: README, if you want to extend or modify cdist. [hacker] - - SEE ALSO -------- - cdist(1)