Migrate README docs to sphinxdoc
Signed-off-by: martin f. krafft <madduck@madduck.net>
diff --git a/doc/source/concepts.rst b/doc/source/concepts.rst
new file mode 100644
index 0000000..67816d8
--- /dev/null
+++ b/doc/source/concepts.rst
@@ -0,0 +1,131 @@
+================
+reclass concepts
+================
+|reclass| assumes a node-centric perspective into your inventory. This is
+obvious when you query |reclass| for node-specific information, but it might not
+be clear when you ask |reclass| to provide you with a list of groups. In that
+case, |reclass| loops over all nodes it can find in its database, reads all
+information it can find about the nodes, and finally reorders the result to
+provide a list of groups with the nodes they contain.
+
+Since the term "groups" is somewhat ambiguous, it helps to start off with
+a short glossary of |reclass|-specific terminology:
+
+============ ==============================================================
+Concept Description
+============ ==============================================================
+node A node, usually a computer in your infrastructure
+class A category, tag, feature, or role that applies to a node
+ Classes may be nested, i.e. there can be a class hierarchy
+application A specific set of behaviour to apply
+parameter Node-specific variables, with inheritance throughout the class
+ hierarchy.
+============ ==============================================================
+
+A class consists of zero or more parent classes, zero or more applications,
+and any number of parameters.
+
+A node is almost equivalent to a class, except that it usually does not (but
+can) specify applications.
+
+When |reclass| parses a node (or class) definition and encounters a parent
+class, it recurses to this parent class first before reading any data of the
+node (or class). When |reclass| returns from the recursive, depth first walk, it
+then merges all information of the current node (or class) into the
+information it obtained during the recursion.
+
+Furthermore, a node (or class) may define a list of classes it derives from,
+in which case classes defined further down the list will be able to override
+classes further up the list.
+
+Information in this context is essentially one of a list of applications or
+a list of parameters.
+
+The interaction between the depth-first walk and the delayed merging of data
+means that the node (and any class) may override any of the data defined by
+any of the parent classes (ancestors). This is in line with the assumption
+that more specific definitions ("this specific host") should have a higher
+precedence than more general definitions ("all webservers", which includes all
+webservers in Munich, which includes "this specific host", for example).
+
+Here's a quick example, showing how parameters accumulate and can get
+replaced.
+
+ All "unixnodes" (i.e. nodes who have the ``unixnode`` class in their
+ ancestry) have ``/etc/motd`` centrally-managed (through the ``motd``
+ application), and the `unixnode` class definition provides a generic
+ message-of-the-day to be put into this file.
+
+ All descendants of the class ``debiannode``, a descendant of ``unixnode``,
+ should include the Debian codename in this message, so the
+ message-of-the-day is overwritten in the ``debiannodes`` class.
+
+ The node ``quantum.example.org`` (a `debiannode`) will have a scheduled
+ downtime this weekend, so until Monday, an appropriate message-of-the-day is
+ added to the node definition.
+
+ When the ``motd`` application runs, it receives the appropriate
+ message-of-the-day (from ``quantum.example.org`` when run on that node) and
+ writes it into ``/etc/motd``.
+
+At this point it should be noted that parameters whose values are lists or
+key-value pairs don't get overwritten by children classes or node definitions,
+but the information gets merged (recursively) instead.
+
+Similarly to parameters, applications also accumulate during the recursive
+walk through the class ancestry. It is possible for a node or child class to
+*remove* an application added by a parent class, by prefixing the application
+with `~`.
+
+Finally, |reclass| happily lets you use multiple inheritance, and ensures that
+the resolution of parameters is still well-defined. Here's another example
+building upon the one about ``/etc/motd`` above:
+
+ ``quantum.example.org`` (which is back up and therefore its node definition
+ no longer contains a message-of-the-day) is at a site in Munich. Therefore,
+ it is a child of the class ``hosted@munich``. This class is independent of
+ the ``unixnode`` hierarchy, ``quantum.example.org`` derives from both.
+
+ In this example infrastructure, ``hosted@munich`` is more specific than
+ ``debiannode`` because there are plenty of Debian nodes at other sites (and
+ some non-Debian nodes in Munich). Therefore, ``quantum.example.org`` derives
+ from ``hosted@munich`` _after_ ``debiannodes``.
+
+ When an electricity outage is expected over the weekend in Munich, the admin
+ can change the message-of-the-day in the ``hosted@munich`` class, and it
+ will apply to all hosts in Munich.
+
+ However, not all hosts in Munich have ``/etc/motd``, because some of them
+ are of class ``windowsnode``. Since the ``windowsnode`` ancestry does not
+ specify the ``motd`` application, those hosts have access to the
+ message-of-the-day in the node variables, but the message won't get used…
+
+ … unless, of course, ``windowsnode`` specified a Windows-specific
+ application to bring such notices to the attention of the user.
+
+It's also trivial to ensure a certain order of class evaluation. Here's
+another example:
+
+ The ``ssh.server`` class defines the ``permit_root_login`` parameter to ``no``.
+
+ The ``backuppc.client`` class defines the parameter to ``without-password``,
+ because the BackupPC server might need to log in to the host as root.
+
+ Now, what happens if the admin accidentally provides the following two
+ classes?
+
+ - ``backuppc.client``
+ - ``ssh.server``
+
+ Theoretically, this would mean ``permit_root_login`` gets set to ``no``.
+
+ However, since all ``backuppc.client`` nodes need ``ssh.server`` (at least
+ in most setups), the class ``backuppc.client`` itself derives from
+ ``ssh.server``, ensuring that it gets parsed before ``backuppc.client``.
+
+ When |reclass| returns to the node and encounters the ``ssh.server`` class
+ defined there, it simply skips it, as it's already been processed.
+
+Now read about :doc:`operations`!
+
+.. include:: substs.inc