From a6b8359f6ac3da95ef9e4d740838a166081090cd Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sat, 26 Dec 2015 20:17:00 +0100 Subject: [PATCH] Added docs for build programs. --- content/docs/api/build/artifact/contents.lr | 2 ++ .../build/program/build-artifact/contents.lr | 16 +++++++++ content/docs/api/build/program/contents.lr | 22 ++++++++++++ .../program/declare-artifact/contents.lr | 23 ++++++++++++ .../program/iter-child-sources/contents.lr | 19 ++++++++++ .../program/produce-artifacts/contents.lr | 17 +++++++++ .../docs/api/build/program/source/contents.lr | 10 ++++++ .../plugins/events/before-build/contents.lr | 35 +++++++++++++++++++ content/docs/content/alts/contents.lr | 6 ++++ content/docs/plugins/list/contents.lr | 4 +++ content/docs/project/file/contents.lr | 5 +++ content/docs/templates/contents.lr | 5 +++ 12 files changed, 164 insertions(+) create mode 100644 content/docs/api/build/program/build-artifact/contents.lr create mode 100644 content/docs/api/build/program/contents.lr create mode 100644 content/docs/api/build/program/declare-artifact/contents.lr create mode 100644 content/docs/api/build/program/iter-child-sources/contents.lr create mode 100644 content/docs/api/build/program/produce-artifacts/contents.lr create mode 100644 content/docs/api/build/program/source/contents.lr create mode 100644 content/docs/api/plugins/events/before-build/contents.lr diff --git a/content/docs/api/build/artifact/contents.lr b/content/docs/api/build/artifact/contents.lr index 1005f11f..d1bab7ea 100644 --- a/content/docs/api/build/artifact/contents.lr +++ b/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 diff --git a/content/docs/api/build/program/build-artifact/contents.lr b/content/docs/api/build/program/build-artifact/contents.lr new file mode 100644 index 00000000..69b78a8d --- /dev/null +++ b/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. diff --git a/content/docs/api/build/program/contents.lr b/content/docs/api/build/program/contents.lr new file mode 100644 index 00000000..e93ef159 --- /dev/null +++ b/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. diff --git a/content/docs/api/build/program/declare-artifact/contents.lr b/content/docs/api/build/program/declare-artifact/contents.lr new file mode 100644 index 00000000..dca5c450 --- /dev/null +++ b/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. diff --git a/content/docs/api/build/program/iter-child-sources/contents.lr b/content/docs/api/build/program/iter-child-sources/contents.lr new file mode 100644 index 00000000..02cdda93 --- /dev/null +++ b/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 +``` diff --git a/content/docs/api/build/program/produce-artifacts/contents.lr b/content/docs/api/build/program/produce-artifacts/contents.lr new file mode 100644 index 00000000..79df873f --- /dev/null +++ b/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. diff --git a/content/docs/api/build/program/source/contents.lr b/content/docs/api/build/program/source/contents.lr new file mode 100644 index 00000000..f087c1c3 --- /dev/null +++ b/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/). diff --git a/content/docs/api/plugins/events/before-build/contents.lr b/content/docs/api/plugins/events/before-build/contents.lr new file mode 100644 index 00000000..7a3a3462 --- /dev/null +++ b/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 +``` diff --git a/content/docs/content/alts/contents.lr b/content/docs/content/alts/contents.lr index d878e0dc..15933242 100644 --- a/content/docs/content/alts/contents.lr +++ b/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 diff --git a/content/docs/plugins/list/contents.lr b/content/docs/plugins/list/contents.lr index 0bc96dac..6eaed101 100644 --- a/content/docs/plugins/list/contents.lr +++ b/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. diff --git a/content/docs/project/file/contents.lr b/content/docs/project/file/contents.lr index 8c855f61..cfe0780b 100644 --- a/content/docs/project/file/contents.lr +++ b/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 diff --git a/content/docs/templates/contents.lr b/content/docs/templates/contents.lr index 190837c0..a2aaf675 100644 --- a/content/docs/templates/contents.lr +++ b/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