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)
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.
Use boil --help
to see the list of available commands and boil <command> --help
to see usage information for any command.
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
.
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.
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>
.
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.
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.