API Documentation

soho.builder module

class soho.builder.Builder(asset_dir, assets_only, base_url, do_nothing, force, hide_index_html, locale_dir, ignore_files, logger, out_dir, src_dir, sitemap, template, template_dir)

Initialize the builder.

Arguments must be passed by name only. Their order may change in the future.

asset_dir

The directory where assets (images, stylesheets, etc.) live. Must be set to None if no such directory exists.

assets_only

If set, process only assets, not source files. This may be useful if the only changes are on the CSS, for example.

base_url

The base URL of the web site. This is used only to generate the URLs in the Sitemap. If you want the Sitemap to have valid URLs, this variable must be set.

do_nothing

If set, no directories nor files are created. This can be useful to test a new configuration. Note that you can combine this setting with force (see below): nothing will be created either.

force

If set, force the generation of HTML files, even if they have already been generated and are up to date. Note that you can combine this setting with do_nothing (see above).

hide_index_html

If set, /index.html suffixes are removed from:

• the path key that is automatically added in the md binding passed to the template;
• URLs in the Sitemap (if a Sitemap is generated).

ignore_files

A (possibly empty) sequence of regular expressions. If the path of a file matches one of these expressions, it will not be processed.

locale_dir

The directory where translations are stored. Must be set to None if no such directory exists.

logger

The logger to be used.

out_dir

The directory where the web site will be generated. This directory will be created if it does not exist.

src_dir

The directory where source files live.

sitemap

The name of the Sitemap file. Must be set to None if you do not want such a file to be generated.

template

The filename of the template to use. It must not be a relative or absolute path to the file (like /path/to/templates/layout.pt) but only a filename (layout.pt).

template_dir

The directory where templates live.

soho.generators package

class soho.generators.BaseGenerator

The base class that any generator must implement.

generate(path)

Return a tuple that consists of the metadata and the HTML fragment generated from the file at the given path.

soho.generators.register_generator(spec, *ext)

Register a generator.

spec

a string that represents the full path to a class, for example 'soho.generators.rst.RSTGenerator'. The class must implement the same interface as soho.generators.BaseGenerator.

ext

one or more file extensions to which the plugin will be associated. At least one file extension must be provided. File extensions should not contain the dot, for example 'html', not '.html'.

soho.renderers package

class soho.renderers.BaseRenderer(template_path)

The base class that any renderer must implement.

There is only one renderer for now, so the API is subject to change (as soon as a second renderer is implemented).

render(**bindings)

Render the template with the given bindings.

soho.renderers.register_renderer(spec, *ext)

Register a renderer.

spec

a string that represents the full path to a class, for example 'soho.renderers.zpt.ZPTRenderer'. The class must implement the same interface as soho.renderers.BaseRenderer.

ext

one or more file extensions to which the plugin will be associated. At least one file extension must be provided. File extensions should not contain the dot, for example 'html', not '.html'.