Welcome to the Novella documentation!

Novella is a build system for processing files in a temporary directory isolated from the project source code. It is designed for the preprocessing of documentation source code such as Markdown files before they are passed into a static site generator such as Mkdocs or Hugo. Novella was designed as the backbone for Pydoc-Markdown, but can be used independently.

Check out the Novella Documentation for more information.

Note: Novella is currently a work in progress project and is considered unstable.

Introduction

The build process is described using a build.novella file using the Craftr-Dsl configuration language, which is (almost) a superset of Python. The novella program executes the script, exposes the options declared within to the command-line interface and executes the pipeline.

usage: novella [--version] [-h] [-i TEMPLATE] [-c PATH] [-d DIRECTORY]
               [-b PATH] [-r] [--dot] [--intercept ACTION] [--serve]
               [--port PORT] [--site-dir PATH] [--base-url URL]

options:
  --version             show program's version number and exit
  -h, --help            Show this help output.
  -i TEMPLATE, --init TEMPLATE
                        Create a `build.novella` file initialized from a
                        template. Available templates are: "mkdocs", "hugo"
  -c PATH, --config-file PATH
                        The configuration file to load. Can be a
                        pyproject.toml in which case the code is looked up
                        under the tool.novella.script key. (default: None)
  -d DIRECTORY, --directory DIRECTORY
                        Switch to the specified directory before executing the
                        configuration file.
  -b PATH, --build-directory PATH
                        The build directory. If not specified, a temporary
                        directory will be created.
  -r, --use-reloader    Enable reloading, which will re-execute the pipeline
                        if a watched file changes.
  --dot                 Produce a DotViz representation of the build graph.
  --intercept ACTION    The name of an action to intercept and pause the
                        execution, waiting for user input to continue. Useful
                        for debugging intermediate steps of the build process.
                        Currently, the action name must be matched exactly and
                        actions can only be intercepted before they are run.
                        If this option is provided, all possible intercept
                        points are logged to the console.

template (mkdocs):
  --serve               Use mkdocs serve
  --port PORT           The port to serve under
  --site-dir PATH       Build directory for MkDocs (defaults to "_site")
  --base-url URL        The base URL to prefix to autogenerated link inside
                        the documentation.

Note

The example above is the output for novella -h for the script that generates this documentation. The script argument group contains the options exposed by the build script indirectly through the usage of the mkdocs template.