diff --git a/doc/.gitignore b/doc/.gitignore
index eebb7a8e6f3c6062227e4766c91434ec2c867235..e85f14c7e6dd237a033bf21141a29e755d8749cb 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,2 +1,2 @@
-muppet*.rst
+muppet.*.rst
 modules.rst
diff --git a/doc/doc-gather.rst b/doc/doc-gather.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2e23c6564cd462f59bd60106ff5c1387bf0a7acd
--- /dev/null
+++ b/doc/doc-gather.rst
@@ -0,0 +1,30 @@
+Gathering information
+=====================
+
+For each module (``get_module``)
+
+run ``puppet-strings`` (todo hyperlink) on the module, using the hash
+of ``metadata.json`` as the cache key
+
+
+Manual documentation files
+--------------------------
+
+``*.md`` + ``LICENSE``
+
+
+Parsing Puppet Code
+-------------------
+
+``puppet strings --format json`` is run, generating a json
+representation of the Puppet code. However, this format is overly
+verbose. So it's passed to ``muppet.puppet.parser.puppet_parser``
+(TODO link) which transforms it into a much simpler json tree.
+
+This is then passed to ``muppet.puppet.ast.build_ast`` (TODO link)
+which creates an AST in python objects.
+
+These modes can be tested with
+
+.. code-block:: sh
+    python -m muppet.puppet {parser,ast,serialize}
diff --git a/doc/formatting-output.rst b/doc/formatting-output.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5edf7ff3e984e3cdea1209a87a4bc9a283e5b857
--- /dev/null
+++ b/doc/formatting-output.rst
@@ -0,0 +1,7 @@
+Formatting Output
+=================
+
+.. toctree::
+
+   syntax-highlighting
+
diff --git a/doc/index.rst b/doc/index.rst
index f26c9c623744fa716ee69164531b496b7367c2ee..fb3d599d1ec45f943ac1d4518e321eecd5f80a52 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,13 +6,17 @@
 Welcome to Muppet Strings's documentation!
 ==========================================
 
+Muppet Strings is a tool for documenting entire Puppet environments.
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
-   modules
-
-Here is some content.
+   doc-gather
+   output-formats
+   syntax-highlighting
+   parser-combinator
+   muppet
 
 Indices and tables
 ==================
diff --git a/doc/muppet.rst b/doc/muppet.rst
new file mode 100644
index 0000000000000000000000000000000000000000..326920e7fc8d71e6b0a794bab258e2f98825dee2
--- /dev/null
+++ b/doc/muppet.rst
@@ -0,0 +1,39 @@
+muppet package
+==============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   muppet.puppet
+   muppet.syntax_highlight
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   muppet.breadcrumbs
+   muppet.cache
+   muppet.format
+   muppet.gather
+   muppet.intersperse
+   muppet.lookup
+   muppet.markdown
+   muppet.output
+   muppet.parser_combinator
+   muppet.symbols
+   muppet.tabs
+   muppet.templates
+   muppet.util
+
+Module contents
+---------------
+
+.. automodule:: muppet
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/output-formats.rst b/doc/output-formats.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6b83ab2f485fa6b86fc12a407a7d7e5738c114c9
--- /dev/null
+++ b/doc/output-formats.rst
@@ -0,0 +1,29 @@
+Output Formats
+==============
+
+TODO something here about how output can be generated (see
+muppet.puppet.format)
+
+
+Output is handled module per module.
+
+- index.html
+- *REFERENCE*/index.html
+- ...
+- manifests/
+  - *classname*
+    - index.html
+    - source.pp.html
+    - source.pp.txt
+  - ...
+
+For each *class* (or *resource*, *type-alias*, ...) a directory is
+generated. The index.html contains the documentation for the class,
+followed by the source code, but syntax highlighted and hyperlinked.
+
+TODO link to parser combinator usage here.
+
+TODO source.pp.html isn't needed since "rendered" now contains the
+original source code.
+
+source.pp.txt contains the unaltered source, as it appeared on disk.
diff --git a/doc/parser-combinator.rst b/doc/parser-combinator.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a556aba8494b78233a6c714f93ea1acb40cfd71c
--- /dev/null
+++ b/doc/parser-combinator.rst
@@ -0,0 +1,2 @@
+Parser Combinator
+=================
diff --git a/doc/syntax-highlighting.rst b/doc/syntax-highlighting.rst
new file mode 100644
index 0000000000000000000000000000000000000000..97db1a4a5c38641caff6e729e55f2dcb23ed0c92
--- /dev/null
+++ b/doc/syntax-highlighting.rst
@@ -0,0 +1,8 @@
+Syntax Highlighting
+===================
+
+andre simons
+plain
+pygments
+
+__init__ finds best possible match