Added docs for build programs.

This commit is contained in:
Armin Ronacher 2015-12-26 20:17:00 +01:00
parent 8baf95aab3
commit a6b8359f6a
12 changed files with 164 additions and 0 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -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 different languages or to customize content specifically for some languages
or regions. 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 ## Enabling Alternatives
To enable alternatives you need to extend your [Project File To enable alternatives you need to extend your [Project File

View File

@ -34,3 +34,7 @@ so they might not keep pace with development on Lektor.
allows deployment of websites to S3 buckets allows deployment of websites to S3 buckets
* [markdown-excerpt :ext](https://github.com/bancek/lektor-markdown-excerpt): * [markdown-excerpt :ext](https://github.com/bancek/lektor-markdown-excerpt):
adds filter for Markdown body 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.

View File

@ -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 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. 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 ## Config Sections
Within the project file there are various configuration selections. The Within the project file there are various configuration selections. The

View File

@ -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 powers of the templating language then you can learn more about it by
reading the [Jinja2 Documentation :ext](http://jinja.pocoo.org/docs). 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 ## Template Folder and Naming
All templates are stored within the `templates/` folder. Templates typically All templates are stored within the `templates/` folder. Templates typically