Composers

handroll uses a plugin system to decide how to process each file type. The plugins are called composers. A composer is provided a source file and can produce whatever output it desires. handroll will load each available composer using setuptools entry points. handroll loads the class and constructs a Composer instance by invoking a no parameter constructor.

class handroll.composers.Composer(config)

Interface for all composers

__init__(config)

Each composer is given the configuration when instantiated.

compose(catalog, source_file, out_dir)

Compose whatever appropriate output is generated by the composer.

Parameters:

• catalog – the TemplateCatalog
• source_file – the filename of the source
• out_dir – the directory to store output

get_output_extension(filename)

Get the extension of the output file generated by this composer.

The filename is required because some composers may vary their extension based on the filename.

permit_frontmatter

Check if frontmatter is permitted for the file type.

A plugin should be added to the handroll.composers entry point group. For example, the MarkdownComposer plugin included by default defines its entry point in setup.py as:

entry_points={
    'handroll.composers': [
        '.md = handroll.composers.md:MarkdownComposer',
    ]
}

This entry point registers the MarkdownComposer class in the handroll.composers.md module for the .md file extension. The example is slightly confusing because the entry point name and the package are the same so here is a fictious example.

A composer class called FoobarComposer defined in another.package for the .foobar file extension would need the following entry point.

entry_points={
    'handroll.composers': [
        '.foobar = another.package:FoobarComposer',
    ]
}

Built-in composers

class handroll.composers.atom.AtomComposer(config)

Compose an Atom feed from an Atom metadata file (.atom).

The AtomComposer parses the metadata specified in the source file and produces an XML Atom feed. AtomComposer uses parameters that are needed by Werkzeug’s AtomFeed API. Refer to the Werkzeug documentation for all the available options.

The dates in the feed should be in RfC 3339 format (e.g., 2014-06-13T11:39:30).

Here is a sample feed:

{
  "title": "Sample Feed",
  "url": "http://some.website.com/archive.html",
  "id": "http://some.website.com/feed.xml",
  "author": "Matt Layman",
  "entries": [
    {
      "title": "Sample C",
      "updated": "2014-05-04T12:00:00",
      "url": "http://some.website.com/c.html",
      "summary": "A summary of the sample post"
    },
    {
      "title": "Sample B",
      "updated": "2014-03-17T12:00:00",
      "url": "http://some.website.com/b.html",
      "summary": "A summary of the sample post"
    },
    {
      "title": "Sample A",
      "updated": "2014-02-23T00:00:00",
      "url": "http://some.website.com/a.html",
      "summary": "A summary of the sample post"
    }
  ]
}

class handroll.composers.CopyComposer(config)

Copy a source file to the destination.

CopyComposer is the default composer for any unrecognized file type. The source file will be copied to the output directory unless there is a file with an identical name and content already at the destination.

class handroll.composers.sass.SassComposer(path=None)

Compose CSS files from Sass files (.scss or .sass).

Sass is a CSS preprocessor to help manage CSS files. The Sass website has great documentation to explain how to use it.

Because Sass is not written in the same language as handroll, it must be installed separately before it can be used. Check out the installation options.