Outline standard more

iffy · Jul 27, 2012 · e32905c · e32905c
1 parent 55ef5f0
commit e32905c
Show file tree

Hide file tree

Showing 15 changed files with 127 additions and 94 deletions.
diff --git a/docs/design.rst b/docs/design.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,23 +8,12 @@ Welcome to mold's documentation!
 
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 4
 
     standard/index
     implementation/index
 
 
-XXX Find a home for these:
-
-.. toctree::
-    :maxdepth: 3
-
-    actors
-    design
-    schema/index
-
-
-
 Indices and tables
 ==================
 

diff --git a/docs/schema/index.rst b/docs/schema/index.rst
diff --git a/docs/actors.rst → docs/standard/actors.rst b/docs/actors.rst → docs/standard/actors.rst
@@ -1,17 +1,23 @@
 Actors
 ======
 
-There are three actors in ``mold``:
 
-    1. Inspectors
-    2. Prescribers (XXX to be defined)
-    3. Conformers
+Fact Checker
+------------
 
+Gets the facts about a machine.
 
-Inspectors
+
+Prescriber
 ----------
 
-An *Inspector* observes the current state of resources.
+XXX to be defined
+
+
+Inspector
+---------
+
+The *Inspector* inspects the current state of resources.
 
 It accepts an *Inspection document* conforming to the schema for the given resource type.  It returns an *Observation document* conforming to the schema for the given resource type.
 
@@ -39,26 +45,17 @@ The inspector will return an `Observation document`_ conforming to the file obse
         ...
     }
 
-With ``mold``, you can use *Inspectors* from the command line (this is just one way to access *Inspectors*):
-
-.. code-block:: bash
-
-    mold inspect file /tmp/foo
 
-Go ahead and try it!
+Choreographer
+-------------
 
+Takes the facts, prescription, observed state and lays out the steps.
 
-Prescribers
------------
 
-XXX to be defined
-
-
-Conformers
-----------
+Performer
+---------
 
-A *Conformer* makes necessary changes to a machine in order to
-conform to a prescribed state.
+The *Performer* makes necessary changes to a machine in order to conform to a prescribed state.
 
 It accepts a *Prescription document* conforming to the schema for a given resource.  XXX what it returns is currently undefined.
 
@@ -76,3 +73,6 @@ For example, you might give it this prescription to ensure that the file at ``/t
     }
 
 
+
+
+
diff --git a/docs/standard/design.rst b/docs/standard/design.rst
@@ -0,0 +1,13 @@
+Design
+======
+
+Components
+----------
+
+The `Mold Standard` defines
+
+    1. The **actors** that use and produce
+    2. structured **documents**
+    3. in a pattern of **routines**
+    4. to make **resources** conform to a desired state.
+
diff --git a/docs/standard/documents.rst b/docs/standard/documents.rst
@@ -1,15 +1,8 @@
 Documents
 =========
 
-
-Fact document
--------------
-
-XXX
-
-
-Identity document
------------------
+Identity
+--------
 
 Identity documents uniquely describe a resource.  All identity documents for all resources conform to this schema:
 
@@ -41,8 +34,51 @@ For example, the identity document for the ``/etc/hosts`` file looks like this:
     }
 
 
-Observation document
---------------------
+Fact
+----
+
+Fact documents describe the (relatively) immutable characteristics of a system.  These documents must conform to this schema:
+
+XXX include schema
+
+Here's an example fact document:
+
+.. code-block:: javascript
+
+    {
+        'os': {
+            'kind': 'linux',
+            'distro': 'ubuntu',
+            'version': '12.10',
+        },
+    }
+
+
+Prescription
+------------
+
+Prescription documents describe the **desired** state of a resource.  Each resource type has its own schema for its *Prescription documents*.  You can see the complete list of resource-specific *Prescription documents* here XXX.
+
+These documents are given to `Conformers`_ which make the changes necessary to match the prescription.
+
+For example, if we want to make sure the file ``/tmp/foo`` does not exist, we could prescribe that with this document:
+
+.. code-block:: javascript
+
+    {
+        "kind": "file",
+        "name": "/tmp/foo",
+        "exists": false
+    }
+
+
+XXX include schema
+
+XXX The prescription is actually a list of Prescriptions.  Somehow, each one should be associated with which steps are a result of it and should be cast into buckets depending on step success/failure (note from notebook -- may overlap with steps document).
+
+
+Observation
+-----------
 
 Observation documents describe the **actual** state of a resource.  Each resource type has its own schema for its *Observation documents*.  You can see the complete list of resource-specific *Observation documents* here XXX.
 
@@ -64,21 +100,16 @@ For example, a ``file`` resource observation document might look like this:
     }
 
 
-Prescription document
----------------------
+XXX include schema
 
-Prescription documents describe the **desired** state of a resource.  Each resource type has its own schema for its *Prescription documents*.  You can see the complete list of resource-specific *Prescription documents* here XXX.
 
-These documents are given to `Conformers`_ which make the changes necessary to match the prescription.
+Steps
+-----
 
-For example, if we want to make sure the file ``/tmp/foo`` does not exist, we could prescribe that with this document:
+Steps documents contain the steps a Performer needs to follow to bring about the desired state.
 
-.. code-block:: javascript
+Steps documents reference 
 
-    {
-        "kind": "file",
-        "name": "/tmp/foo",
-        "exists": false
-    }
+XXX include schema
 
 
diff --git a/docs/standard/index.rst b/docs/standard/index.rst
@@ -1,9 +1,13 @@
 Mold Standard
 =============
 
-This and the linked documents, known collectively as the `Mold Standard`, define     a standard for configuration management systems.
+This and the linked documents, known collectively as the `Mold Standard`, define a standard for configuration management systems.
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
+    design
+    actors
     documents
+    routines
+    schema/index
diff --git a/docs/standard/resources.rst b/docs/standard/resources.rst
diff --git a/docs/standard/routines.rst b/docs/standard/routines.rst
@@ -0,0 +1,24 @@
+Routines
+========
+
+
+Mold
+----
+
+This routine finds out what state a system should be in, then does what's needed to make it conform to that state.
+
+Here's some pseudo code describing how the state of a machine is set:
+
+.. code-block:: python
+
+    facts = FactChecker()
+    prescription = Prescriber(facts)
+    while 1:
+        observation = Observer(prescription)
+        steps = Choreographer(facts, prescription, observation)
+        if not steps:
+            break
+        Performer(steps)
+
+
+An implementation might replace some or most of those function calls with calls to remote systems.  Neither error handling nor logging are shown in the pseudo code.
diff --git a/docs/schema/file.inspection.rst → docs/standard/schema/file.inspection.rst b/docs/schema/file.inspection.rst → docs/standard/schema/file.inspection.rst
diff --git a/docs/schema/file.observation.rst → docs/standard/schema/file.observation.rst b/docs/schema/file.observation.rst → docs/standard/schema/file.observation.rst
diff --git a/docs/schema/file.prescription.rst → docs/standard/schema/file.prescription.rst b/docs/schema/file.prescription.rst → docs/standard/schema/file.prescription.rst
diff --git a/docs/schema/file.rst → docs/standard/schema/file.rst b/docs/schema/file.rst → docs/standard/schema/file.rst
diff --git a/docs/standard/schema/index.rst b/docs/standard/schema/index.rst
@@ -0,0 +1,7 @@
+Resources
+=========
+
+.. toctree::
+    :maxdepth: 2
+
+    file
diff --git a/extract_schema.py b/extract_schema.py
@@ -20,7 +20,7 @@ class Options(usage.Options):
     ]
 
     optParameters = [
-        ['destination', 'd', root.child('docs').child('schema').path,
+        ['destination', 'd', root.child('docs').child('standard').child('schema').path,
             "Directory in which to dump the rst files"],
         ['template-root', 't', root.child('templates').path,
             "Template directory to be used for rendering the files."],
@@ -67,4 +67,4 @@ def main():
 
 
 if __name__ == '__main__':
-    main()
+    main()