renderdown 0.2.0

Generate Markdown text from templates.

RenderDown

Generate Markdown text from templates; that is, the result of rendering is Markdown text, not HTML. This is useful for generating documents published on a Markdown platform like GitHub Wikis.

Usage

The simplest way to use RenderDown is to invoke it from the commandline:

renderdown.py TEMPLATE [--assign KEY=VALUE] [--outdir OUTDIR]

The required TEMPLATE argument is the path to a template file. Simple variables may be passed to the template with the --assign option. If the --outdir option is set, multi-file documents can be created, written to files in the output directory; if unset, the multiple pages are appended together and printed to stdout.

RenderDown can also be used as a library. The API.md file (generated using RenderDown and CartogrAPI) is a reference of RenderDown's API.

Templates

Templates are rendered with Mako. A doc variable is added to the namespace of all templates (see API.md for a description of the functions on doc). For example, if mytemp.mako is a template defined as follows:

# ${title}

Here are two bullet points:
${ doc.listitem("the first point") }
${ doc.listitem("note how wrapped lines\nare indented") }

${ doc.blockquote(
    "the same is true for blockquotes, except the > character is\n"
    "repeated on the wrapped lines.")
}

The the following call the RenderDown will render the template:

$ python renderdown.py example.md --assign title="Hello World"
# Hello World

Here are two bullet points:
* the first point
* note how wrapped lines
  are indented

> the same is true for blockquotes, except the > character is
> repeated on the wrapped lines.

The original use case for rendering Markdown is for publishing Python API documentation on GitHub Wikis, so the default templates target that platform.

The templates are defined for rendering packages, modules, classes, methods, and functions in a fairly generic way (inspired by documentation), but they can be reconfigured and specialized for individual projects.

Requirements

• Python 3.3+
• Mako

How to Test

Run the following command to test:

$ pip install -r requirements.txt   # install dependencies
$ pip install -e .                  # to import in tests
$ python setup.py test              # run the test cases

License

MIT; see LICENSE for more information.

Project History

This project was created by Michael Wayne Goodman (@goodmami) and is now owned and maintained by Jeff Hung (@jeffhung).

Links

• Mako - templating engine
• D3.js's wiki - provided aesthetic inspiration for the wiki organization
• CartogrAPI - used to map out Python APIs
• Related Software:
  • doc2md
  • pdoc
  • Sphinx AutoAPI