doxx Template Files

What is a Template?

It is a file that provides a reusable storage mechanism for any type of text. doxx templates allow you to generate new text files verbatim from the text in the template, or to generate versions that can be customized with text replacements during the build process.

Template files work hand-in-hand with key files to create a reusable doxx build project.

The Template File Structure

doxx Templates Include:

  1. YAML build specification header section
  2. template text section (including optional named text replacement tags)
  3. a base file name that corresponds to the outfile base file name by default
  4. a .doxt file extension

Build Specification Header

doxx requires input from the template designer to determine the name, path, and type of file to build from the template. This information is defined in the build specification section at the head of the template file.

This header section is enclosed between required ---doxx--- delimiters and uses YAML key: value syntax:

---doxx---

basename: example
extension: py
destination_directory: build

---doxx---

Available build specification fields include:

  • extension:
  • basename:
  • destination_directory:
  • verbatim:

extension : (Required) the rendered file extension. It is not necessary to include a period in the extension string (i.e. txt rather than .txt is acceptable). Include the extension field but leave it blank to indicate that no file extension should be used (e.g. for a file that you want to name LICENSE).

basename : (Optional) base file name for the rendered template file. The default is the basename of the template file if this field is not included in the template.

destination_directory : (Optional) sub-directory path for the rendered template file. The default is the root project directory where the key file is located if this field is not included in the template. Use standard POSIX path syntax with forward slash separators / between directory names for multiple sub-directory levels (including on Windows systems).

verbatim : (Optional) takes a boolean value (true or false) to specify whether doxx should write the template text verbatim to disk. This is a speedup option that tells doxx to skip the scan for text replacement sites in the file when they are not necessary. If it is not included, doxx will always scan for text replacement sites in the template file.

Note that if you define destination_directory, the build directory path is relative to the root directory where the doxx build command is executed on the key file during the build, not the directory where the template file is located. This design is intentional. It allows you to store your templates outside of new projects for reuse.

The Template Text

The template is included immediately following the second ---doxx--- delimiter. Full UTF-8 character support is provided for text used in your template.

If your template file provides users with the option to perform text replacements, insert named text replacement tags in the appropriate sites of the template.

doxx uses double curly braces surrounding the text replacement tag name to indicate replacement sites:

{{tagname}}

You can include any number of replacement tags in your template files. If you include more than one tag with the same name in your file, doxx will perform the same text replacement at each site in the rendered file.

Tag Name Best Practices

  • Use CamelCase or dashed-names rather than including spaces between multi-word tag names
  • Make your tag names descriptive if you intend to distribute your templates to others. This makes interpretation much easier on the user side.
  • Tag names can include any character in the UTF-8 character set

Beware

Spaces are important in tag syntax. Do not include spaces between the curly braces and the tag name that they surround.

This is correct: {{tagname}}

This is not correct: {{ tagname }}

Project users include the same replacement tag name in their key file with a text string that defines the replacement text at the tag site.

Here is an example of a complete template file for a Python module stub with replacement tags for a class name and docstring:

---doxx---

extension: py
destination_directory: build

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

class {{classname}}(object):
    """{{docstring}}"""
    def __init__(self):
        pass

Template File Stub Generator

doxx generates a template file stub in the current working directory with the make command. This file provides all of the formatting described above so that you can dive right in and develop a template rather than coming back here to look up the template file specs.

See the make command documentation for details.


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