huge documentation cleanup

Signed-off-by: Nico Schottelius <nico@brief.schottelius.org>
This commit is contained in:
Nico Schottelius 2012-01-17 23:53:58 +01:00
parent cae332dcf8
commit 22f242b1d9
7 changed files with 23 additions and 62 deletions

View file

@ -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]
--------------------------------------------------------------------------------

View file

@ -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/<name>::
@ -90,7 +90,7 @@ conf/type/<name>/::
This directory is referenced by the variable __type (see below).
conf/type/<name>/man.text::
Manpage in Asciidoc format (nequired for inclusion into upstream)
Manpage in Asciidoc format (required for inclusion into upstream)
conf/type/<name>/manifest::
Used to generate additional objects from a type.
@ -199,7 +199,7 @@ __type_explorer::
SEE ALSO
--------
- cdist(7)
- cdist(1)
COPYING

View file

@ -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).

View file

@ -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).

View file

@ -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).

View file

@ -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).

View file

@ -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)