parboil 0.9.3

Create reusable boilerplate templates to kickstart your next project.

:rice: Parboil

Project Boilerplate Generator

With Parboil you can create reusable boilerplate templates to kickstart your next project.

!!! note ""

_Parboil_ is a Python rewrite of [boilr](https://github.com/tmrts/boilr) by [Tamer Tas](https://github.com/tmrts)

---

pipx install parboil Successfully installed parboil boil install -d jneug/parboil-license [✓] Installed recipe parboil-license [i]     Use with boil use parboil-license boil use parboil-license [i] Used prefilled value for "Author" [i] Used prefilled value for "Email" [?] Enter a value for "Year" (2022): [?] Choose a value for "License"     1 - Apache License 2.0     2 - MIT     3 - ISC     4 - GNU GPL v3.0     5 - GNU GPL v2.0     6 - CC-BY 4.0     7 - CC-BY-SA 4.0     8 - CC-0 1.0     Select from 1..9 2 [i] Generated project for recipe "parboil-license" in /Users/xyz/Projects/foo

Installation

Install Python 3 and then Parboil with pip:

pip install parboil

Parboil will install a boil command on your system. Run boil --version to see, if it worked.

Getting started

Use boil --help to see the list of available commands and boil <command> --help to see usage information for any command.

Installing your first template

Parboil maintains a local repository of project templates. To use Parboil you first need to install a template. You can install templates from a local directory or download them from GitHub.

For your first template install jneug/parboil-template from GitHub - a project template to create parboil project templates.

boil install -d jneug/parboil-template pbt

This will download the template from jneug/parboil-template and makes it available under the name pbt. (The -d flag tells Parboil, that you want to download from GitHub and not from a local directory.)

Verify the install with boil list.

Using a template

To use your new template run

boil use pbt new_template

This will create the boilerplate project in the new_template directory. (Omitting the directory will add the template to the current working dir.) Parboil asks you to input some data and then writes the project files.

Uninstall and update

To remove a template run boil uninstall <templatename> and to update from its original source (either a local directory or a GitHub repository) run boil update <templatename>.

Creating your first recipe

The parboil-template is a good starting point to create your own template. Parboil uses Jinja2 to parse the template files and dynamically insert the user information into the template files. That means, you can use all of Jinjas features (and some more), to create your template files.

Let's create a simple project template for meeting logs from scratch.

First, create a directory for your new template. Let's call it meeting_log. Then creat a directory called template and a file called project.json in it.

meeting_log/
├── template/
└── parboil.json

This is the basic structure of a parboil recipe. parboil.json holds the recipe configuration and template the actual template files.

Now open parboil.json in any editor and copy the following text into it:

!!! example

``` json
{
	// Ingredients for the meeting log recipe
	"Author": "",
	"Meeting": "Daily meeting",
	"MeetingNo": 1,
	"Topic": "Planning the day",
	"IamModerator": false,
	"NumberOfTops": 2
}
```

This is a basic recipe that defines five ingredients. Ingredients are essentially variables that are filled in by the user and inserted into the template files. The key of each entry is the field name, the value is the default. An empty string means, the key is required everytime.

!!! tip

As you can see in the example above, a recipe is defined in json with comments format. 

Now we need to add the file(s) that should be created by Parboil. Create {{Meeting}}_log.md in the template directory. And enter this text:

# Meeting notes for {{ Meeting|title }} #{{ MeetingNo }} 

> Date: {% time '%Y-%m-%d' %}
> Topic: {{ Topic }}
> Author: {{ Author }}
{% if IamModerator %}> Moderator: {{ Author }}{% endif %}

## Topics

{% for t in range(NumberOfTops) %}
{{t|format('{:<2}')}}. 
{% endfor %}

## Notes

The template uses Jinjas syntax to add the field values. For example {{ Author }} will be replaced with the name you entered while prompted. Note that you can use the fields in filenames, too.

You can use any Jinja macros and filters in your templates. {{ Meeting|title }} will tranform the value of "Meeting" into titlecase. {% if IamModerator %} is a conditional.

For more information read the wiki page on template creation.

Some more template creation

You can do some more complex stuff with templates. For example you might want to name the logfile in the example above with the current date and the meetings number padded with zeros to two digits. Also, the meeting name should be filtered for use in filenames. You would need to name the file like this:

{% time '%Y-%m-%d' }_{{ '{:02}'.format(MeetingNo) }}-{{ Meeting|fileify }}.md

The use of special chars works on many systems, but now all. Also, the filename becomes hard to read.

To deal with this, you can rename your files from the project.json config file. Add a files object next to the fields and map the filenames to the rename pattern:

{
	"fields": {
		...
	},
	"files": {
		"meeting-log.md": "{% time '%Y-%m-%d' }_{{ '{:02}'.format(MeetingNo) }}-{{ Meeting|fileify }}.md"
	}
}

Now you can name the log file meeting-log.md and will get something like 2021-03-10_04-Daily Standup.md as a result.

There are some more features for creating complex templates, like subtemplates (for example run a template to generate a license file inside differnt app project templates), selective file inclusion, template inheritance or dealing with empty files.