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.

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.j2.Jinja2Composer(config)¶

Compose any content from a Jinja 2 template files (.j2).

The Jinja2Composer takes a template file and processes it through the Jinja 2 renderer. The site configuration is provided to the context for access to global data.

The output file uses the same name as the source file with the .j2 extension removed.

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.md.MarkdownComposer(config)¶

Compose HTML from Markdown files (.md).

The first line of the file will be used as the title data for the template. All following lines will be converted to HTML and sent to the template as the content data.

The MarkdownComposer supports syntax highlighting using Pygments. Code can be specified using “fenced code” triple backticks.

```python
class Foo(object):
    '''This sample code would be highlighted in a Python style.'''
```

Use pygmentize to create your desired CSS file. Refer to the Pygments documentation for more information.

$ pygmentize -S default -f html > pygments.css

The MarkdownComposer generates better typographical quotes by using the SmartyPants library.

class handroll.composers.rst.ReStructuredTextComposer(config)¶

Compose HTML from reStructuredText files (.rst).

The first line of the file will be used as the title data for the template. All following lines will be converted to HTML and sent to the template as the content data.

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.

class handroll.composers.txt.TextileComposer(config)¶

Compose HTML from Textile files (.textile).

The first line of the file will be used as the title data for the template. All following lines will be converted to HTML and sent to the template as the content data.