Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
330 lines (204 sloc) 13 KB

doxx Quickstart Guide for Project Developers

The following guide provides an overview of the build files used in a doxx project, and of useful commands for project developers. For more detailed documentation, please follow the links in the guide.

Project Structure

A doxx project includes the following:

  • one key file (default: key.yaml)
  • one or more template files (file extension: .doxt)

The key file is executed to perform the build according to specifications in one or more template files. Template files are a reusable storage mechanism for any type of text that provides your project users with the opportunity to further customize the template files at named text replacement tag positions.

Project Structure Documentation

Template File Structure and Use

A template file includes:

  • YAML project build specification header section
  • template text section
  • ---doxx--- head section delimiters
  • named replacement tags with {{ and }} delimiters (optional)

Available template build specification fields include:

  • extension: (Required)
  • basename: (Optional)
  • destination_directory: (Optional)
  • verbatim: (Optional)

Template Example


basename: example
extension: py
destination_directory: build

#!/usr/bin/env python
# encoding: utf-8

class {{classname}}(object):
    def __init__(self):

Template File Documentation

Key File Structure and Use

A key file includes:

  • YAML build file path specification header section
  • YAML string replacement key section

Available build specification section fields:

  • template: single template file path or URL with one:one key-template mapping
  • templates: multiple template file paths or URLs with one:many key-template mapping
  • project: single project archive tar.gz or .zip file path or URL

Please Note:

  • local template file paths can be absolute paths or relative to the key file
  • use POSIX style file and directory separator characters / (for Windows users too!)
  • remote templates must be accessible by GET request using the http:// or https:// protocol
  • remote template URLs must be surrounded by single or double quotes
  • Replacement string definitions that use YAML special characters must be surrounded by double quotes

Key Files with Local Template Paths


template: example.doxt


classname: AwesomeClass
docstring: a class that does something awesome

templates: [templ1.doxt, templ2.doxt, templ3.doxt]


classname: AwesomeClass
docstring: a class that does something awesome

Key Files with Remote Template Paths


template: ''


classname: AwesomeClass
docstring: a class that does something awesome

templates: ['',


classname: AwesomeClass
docstring: a class that does something awesome

Key File with Local Project Archive Path


project: example.tar.gz


classname: AwesomeClass
docstring: a class that does something awesome

Key File with Remote Project Archive Path


project: ''


classname: AwesomeClass
docstring: a class that does something awesome

Distribution of Key File Stubs

It is good practice to distribute key file stubs with your project. This simplifies the build process for users who should not be expected to know the key file syntax or locate the available named text replacement sites in your template(s). Complete the build specs section with either local project files or the remote URLs where the project files are accessed, and provide an empty list of the available named text replacement tags in your project templates.

You can provide instructions to users with comments in the key file. The # character indicates that the remaining characters on the line are a comment. Here is an example of a key file stub that enables a user to easily complete the key and build their own version of the project:


# Change to example2.doxt for the alternate version
project: example.doxt


# The name of the Python class

# The docstring for the Python class defined in `classname:` above

If the above project is hosted at the URL, the user can pull and unpack the entire project archive to their current working directory with:

$ doxx pull

open the key.yaml file in their favorite text editor, define the classname: and docstring: fields, and build the project with:

$ doxx build

Key File Documentation

Project Archives

Project archives are tar.gz or zip archives of a project directory. doxx can build directly from a project archive file which simplifies key paths for the user when a project becomes large and complex, or the project requires the distribution of binary files in addition to text files.

The required files in a project archive differ slightly from a non-archived project.

Project Archives Include:

  • pkey.yaml key file
  • project.yaml build spec file
  • one or more template files
  • any number of verbatim text files and/or binary files
  • project-specific directory structure

The pkey.yaml file:

  • replaces key.yaml in a project archive.
  • has the same structure and serves the same purpose as a key.yaml file for builds from unpacked archives (e.g. following a doxx pull of the archive file)

The project.yaml file:

  • defines the project build file paths
  • is used to execute builds that take place directly from the project archive file without previously unpacking it
  • includes only the build specification head section of a standard key file

Here is an example of a project.yaml file:


templates: [example.doxt, example2.doxt, example3.doxt]


Project archive template files:

  • do not differ from standard project template files (see Template file section above)

doxx pack (docs) can be used to create tar.gz / zip archives of your project or you can use any other application that is available on your platform to do this.

Builds from local or remote project archive files are supported. Remote project archives must be accessible to doxx by GET request using the http:// or https:// protocol.

Project Archive Documentation

Project Layout and Build Paths

The key.yaml file location defines the root directory of your project build. The rendered file build paths resolve to the current working directory where you execute the doxx build command on this key file.

The template build path can be changed to a different sub-directory with the destination_directory template build spec field. For example, say we have a template file on the path /other/dir/example.doxt that is rendered with a key.yaml file located in a clean project directory called new-project. The rendered file path when the extension build spec field value is 'py' and the destination_directory build spec field value is 'build' would be:

├── new-project          # the new project directory
	├── key.yaml         # the doxx key file (contains path to the template file)
	└── build            # the requested build directory
		└──   # the rendered file

If you remove the optional destination_directory field from your template file, the file write takes place in the root directory:

├── new-project          # the new project directory
	├── key.yaml         # the doxx key file (contains path to the template file)
	└──       # the rendered file

The same principle applies to builds with remote template files.

Project Structure Documentation

Commands for Project Developers

doxx make - Key, Template, and Project Stub Generators

Create a Template File Stub

$ doxx make template

This command writes the template stub stub.doxt to the current working directory.

Create a Key File Stub

$ doxx make key

This command writes the key stub key.yaml to the current working directory.

Generate a Project with File Stubs

$ doxx make project

This command generates the following project directory structure with key and template file stubs:

├── current working directory
	├── pkey.yaml
	├── project.yaml
	└── templates
	    └── stub.doxt

doxx make Documentation

doxx pack - Package a tar.gz or zip Project Archive

tar.gz Archive

$ doxx pack [project directory]

zip Archive

$ doxx pack zip [project directory]

doxx pack Documentation

doxx build - Test Project Builds

Navigate to the root directory of your new project build. This should contain a key.yaml file. Execute the following command:

$ doxx build

doxx build Documentation

just blimpin doxx documentation is licensed under the CC-4.0-Attribution LicenseImprove this Guide