Added docs for build programs.

content/docs/api/build/artifact/contents.lr

@@ -30,3 +30,5 @@ def build_stylesheet(artifact):
     with artifact.open('w') as f:
         f.write('Hello World!\n')
 ```
+---
+module: lektor.builder

content/docs/api/build/program/build-artifact/contents.lr

@@ -0,0 +1,16 @@
+title: build_artifact
+---
+signature: artifact
+---
+summary: Invoked to build a previously declared artifact.
+---
+type: method
+---
+body:
+
+This method is invoked for previously declared artifacts and is supposed to
+write out the artifact.  It's only invoked if the builder decided that the
+artifact is outdated based on the information at hand.
+
+For an example refer to the [add_build_program
+:ref](../../../environment/add-build-program/) documentation.

content/docs/api/build/program/contents.lr

@@ -0,0 +1,22 @@
+title: BuildProgram
+---
+module: lektor.build_programs
+---
+summary: The class for build programs.
+---
+type: class
+---
+body:
+
+A build program is responsible for converting a [Source Object
+:ref](../../db/obj/) into final build artifacts.  Typically such a build
+program implements two methods: [produce_artifacts :ref](produce-artifacts/)
+and [build_artifact :ref](build-artifact/).
+
+The former should invoke [declare_artifact :ref](declare-artifact/) for each
+artifact that should be created from the source.  The builder will then
+invoke [build_artifact :ref](build-artifact/) for each of these declared
+artifacts if the builder determiend that the artifact needs to be built.
+
+For an example refer to the [add_build_program
+:ref](../../environment/add-build-program/) documentation.

content/docs/api/build/program/declare-artifact/contents.lr

@@ -0,0 +1,23 @@
+title: declare_artifact
+---
+signature: artifact_name, sources=None, extra=None
+---
+summary: Declares an artifact to build from this program.
+---
+type: method
+---
+body:
+
+This method is supposed to be called from [produce_artifacts
+:ref](../produce-artifacts/).  For each of these invocations the builder will
+later invoke the [build_artifact :ref](../build-artifact/) function.
+
+The parameters behave as follows:
+
+* `artifact_name`: the name of the final artifact that will be built.  This
+  will be converted into a filename appropriate for the operating system
+  automatically and should thus always use forward slashes.
+* `sources`: a list of source filenames that make up the artifact.  This will
+  be tracked as main indication about how artifacts change.
+* `extra`: arbitrary extra information that is associated with the artifact so
+  that [build_artifact :ref](../build-artifact/) can use it.

content/docs/api/build/program/iter-child-sources/contents.lr

@@ -0,0 +1,19 @@
+title: iter_child_sources
+---
+type: method
+---
+summary: Optionally this method can be implemented to produce child sources.
+---
+body:
+
+Optionally a builder can yield further sources that are then picked up by the
+builder and processed normally.  This is how the recursive build process in
+Lektor is implemented for normal records.
+
+## Example
+
+```python
+def iter_child_sources(self):
+    for child in self.sources.children:
+        yield child
+```

content/docs/api/build/program/produce-artifacts/contents.lr

@@ -0,0 +1,17 @@
+title: produce_artifacts
+---
+summary: Method that needs to be overridden for the build to work.
+---
+type: method
+---
+body:
+
+This method needs to be overridden by subclasses.  It's invoked at the
+beginning of the build process and it's purpose is to invoke the
+[declare_artifact :ref](../declare-artifact/) method for each artifact
+that the build should generate.  For each of these invocations later the
+[build_artifact :ref](../build-artifact/) method will be invoked if the
+builder determined that the artifact needs to be rebuild.
+
+For an example refer to the [add_build_program
+:ref](../../../environment/add-build-program/) documentation.

content/docs/api/build/program/source/contents.lr

@@ -0,0 +1,10 @@
+title: source
+---
+summary: A reference to the source object.
+---
+type: property
+---
+body:
+
+This refers to the source object that created the build program.  It's primary
+use is to build the artifact in [build_artifact :ref](../build-artifact/).

content/docs/api/plugins/events/before-build/contents.lr

@@ -0,0 +1,35 @@
+title: before-build
+---
+type: event
+---
+signature: builder, build_state, source, prog
+---
+summary: This event is emitted before an individual source is built.
+---
+body:
+
+This event is emitted right before a source is being built into a final build
+artifact.  Note that this event in itself does not indicate if the build will
+actually take place or not due to the artifact being current already as such
+the usefulness is limited.
+
+The parameters being passed are:
+
+* `builder`: a reference to the builder.
+* `build_state`: a reference to the build state object.
+* `source`: the source object that is being processed. (See
+  [Source Object :ref](../../../db/obj/) for more information)
+* `prog`: the build program that is being used to process the source. (See
+  [Build Program :ref](../../../build/program/) for more information)
+
+!!!! Note that currently both the builder as well as the build state are
+undocumented and unsupported!  This means that if a plugin choses to use those
+references to do something with it they should consider that they might break
+in future versions.
+
+## Example
+
+```python
+def on_before_build(self, source, prog, **extra):
+    print 'building %s' % source.source_filename
+```

content/docs/content/alts/contents.lr

@@ -9,6 +9,12 @@ to a content file.  This allows you to translate your website into many
 different languages or to customize content specifically for some languages
 or regions.
 
+!!!! Alternatives are a fully functional feature in Lektor but very
+underdocumented and lacking in parts.  The result of this is that it might not
+be working exactly as you expect in parts.  In particular one of the limiting
+factors is that you need to have at least one alternative at the URL root or
+the system will refuse to build the website.
+
 ## Enabling Alternatives
 
 To enable alternatives you need to extend your [Project File

content/docs/plugins/list/contents.lr

@@ -34,3 +34,7 @@ so they might not keep pace with development on Lektor.
   allows deployment of websites to S3 buckets
 * [markdown-excerpt :ext](https://github.com/bancek/lektor-markdown-excerpt):
   adds filter for Markdown body excerpt
+
+! Have your own plugin and you want to see it here?  Just [edit this page
+on GitHub :ref](https://github.com/lektor/lektor-website/edit/master/content/docs/plugins/list/contents.lr),
+add your plugin to the list and send a pull request.

content/docs/project/file/contents.lr

@@ -19,6 +19,11 @@ extension or Lektor will not be able to find it.  When Lektor looks for a
 project it looks upwards from the current folder until it finds a single
 file with the `.lektorproject` extension and that's then the root of the project.
 
+!! It's possible to build a Lektor project in the absence of a Project file
+but this usage his heavily discouraged.  It exists primarily for quick
+testing situations.  But don't be confused if you encounter a Lektor project
+that does not come with a corresponding project file.
+
 ## Config Sections
 
 Within the project file there are various configuration selections.  The

content/docs/templates/contents.lr

@@ -12,6 +12,11 @@ be able to generate beautiful websites but if you want to dive deep into the
 powers of the templating language then you can learn more about it by
 reading the [Jinja2 Documentation :ext](http://jinja.pocoo.org/docs).
 
+!! Templates are a very powerful component in Lektor.  A lot of documentation
+about the features of it can be found in the [Jinja2 Documentation
+:ext](http://jinja.pocoo.org/docs) as well as the [Lektor Template API
+Documentation :ext](../api/templates/).
+
 ## Template Folder and Naming
 
 All templates are stored within the `templates/` folder.  Templates typically