moban - 模板 Yet another jinja2 cli command for static text generation¶
| Author: | C.W. |
|---|---|
| Issues: | http://github.com/moremoban/moban/issues |
| License: | MIT |
| Version: | 0.0.6 |
| Generated: | Jan 14, 2019 |
moban brings the high performance template engine (JINJA2) for web into static text generation. It is used in pyexcel project to keep documentation consistent across the documentations of individual libraries.
Installation¶
You can install it via pip:
$ pip install moban
or clone it and install it:
$ git clone http://github.com/moremoban/moban.git
$ cd moban
$ python setup.py install
Quick start¶
Here is a simple example:
$ moban -c data.yml -t my.template
$ cat moban.output
Given data.yml as:
hello: world
and my.template as:
{{hello}}
moban.output will contain:
world
the tutorial has more use cases.
Usage¶
- usage: moban [-h] [-cd CONFIGURATION_DIR] [-c CONFIGURATION]
- [-td [TEMPLATE_DIR [TEMPLATE_DIR …]]] [-t TEMPLATE] [–template_type TEMPLATE_TYPE] [-o OUTPUT] [-f] [-m MOBANFILE]
Yet another jinja2 cli command for static text generation
optional arguments¶
- -h, –help show this help message and exit
- -cd CONFIGURATION_DIR –configuration_dir CONFIGURATION_DIR the directory for configuration file lookup
- -c CONFIGURATION, –configuration CONFIGURATION the dictionary file
- -td [TEMPLATE_DIR [TEMPLATE_DIR …]], –template_dir [TEMPLATE_DIR [TEMPLATE_DIR …]] the directories for template file lookup
- -t TEMPLATE, –template TEMPLATE the template file
- –template_type TEMPLATE_TYPE the template type, default is jinja2
- -o OUTPUT, –output OUTPUT the output file
- -f force moban to template all files despite of .moban.hashes
- -m MOBANFILE, –mobanfile MOBANFILE custom moban file
exit codes¶
- 0 : no changes
- 1 : has changes
- 2 : error occured
Special Filters¶
split_length¶
It breaks down the given string into a fixed length paragraph. Here is the syntax:
{% for line in your_string | split_length(your_line_with) %}
{{line}}
{% endfor %}
It is used to keep changelog formatted in CHANGELOG.rst.jjs in pypi-mobans project
github_expand¶
It expands simple hashtags into github issues. Here is the syntax:
{{ your_github_string | github_expand }}
It makes it easy to mention github reference in change log in all projects. Here is the place it is applied: CHANGELOG.rst.jjs in pypi-mobans project
Here is Grammar in the changelog.yml:
=============== ==============================
Syntax Meaning
=============== ==============================
`#1` moban issues 1
`PR#1` moban pull request 1
`pyexcel#1` other project issues 1
`pyexcel#PR#1` other project pulll request 1
=============== ==============================
More details can be found in moban’s changelog.yml
Tutorial¶
Please clone the moban repository as the data mentioned in the tutorial are stored in examples folder.
Level 1 Jinja2 on command line¶
moban reads data in yaml format, renders a template file in jinja2 format and outputs it to moban.output. By default, it looks for data.yml as its data file
Evaluation¶
Please clone the moban project and install moban:
- $ git clone https://github.com/chfw/moban.git
- $ cd moban $ python setup.py install
Then go to docs/level-1-jinja2-cli. here are different commands to evaluate it:
moban -c data.yml -t a.template
‘moban.output’ is the generated file.
moban -c data.yml -t a.template -o my.output
-o my.output will override the default name
Note
You may simply type the short form:
moban -t a.template
because moban looks for data.yml by default
Level 2: template inheritance¶
Template inheritance is a feature in Jinja2. This example show how it was done. a.template inherits base.jj2, which is located in .moban.td, the default template directory.
Evaluation¶
Please go to docs/level-2-template-inheritance, here is the command to launch it:
moban -c data.yaml -t a.template
a.template inherits .moban.td/base.jj2.
Level 3: data override¶
What moban bring on the table is data inheritance by introducing overrides key word in the yaml file:
overrides: data.base.yaml
....
And .moban.cd is the default directory where the base data file can be placed.
Evaluation¶
Please change directory to docs/level-3-data-override directory.
In this example, data.yaml overrides .moban.cd/data.base.yaml, here is the command to launch it:
moban -c data.yaml -t a.template
‘a.output’ is the generated file:
========header============
world
shijie
========footer============
Level 4: single command¶
If you use moban regularly and operates over a number of files, you may consider write a .moban.yml, which is a mini script file that commands moban to iterate through a number of files
Evaluation¶
Please go to docs/level-4-single-command directory.
Here is the .moban.yml, whihc replaces the command in level 3:
targets:
- a.output: a.template
where targets should lead an array of dictionaries.
Here is how to launch it .. code-block:: bash
moban
‘a.output’ is the generated file:
========header============
world
shijie
========footer============
Level 5: custom configuration¶
With .moban.yml, you can even change default data directory .moban.cd and default template directory .moan.td. Read this example:
configuration:
configuration_dir: 'custom-config'
template_dir:
- custom-templates
- cool-templates
- '.'
targets:
- a.output: a.template
where configuration lead a dictionary of key words:
- configuration_dir - the new configuration directory
- template_dir - an array of template directories
Evaluation¶
Please go to docs/level-5-custom-configuration directory.
Here is the command to launch it:
moban
‘a.output’ is the generated file:
========header============
world
shijie
this demonstrations jinja2's include statement
========footer============
Level 6: Complex Configuration¶
On top of level 5, you could have a common template, where data and output change. In the following example:
configuration:
configuration_dir: 'custom-config'
template_dir:
- custom-templates
- cool-templates
- '.'
template: a.template
targets:
- output: a.output
configuration: data.yml
- output: a.output2
configuration: data2.yml
where template under confiugration needs a template file, which will be a default template across targets. And in this example, the expand form of targets is illustrated:
- {
- “output”: ‘an output file’, “configuration”: ‘data file’, “template”: “the template file”
}
Evaluation¶
Please go to docs/level-6-complex-configuration directory.
Here is the command to launch it:
moban
‘a.output’ is the generated file:
========header============
world
shijie
this demonstrations jinja2's include statement
========footer============
a.output2 is:
========header============
world2
shijie
this demonstrations jinja2's include statement
========footer============
For more complex use case, please look at its usage in pyexcel project
Change log¶
0.1.4 - 29-May-2018¶
0.1.1 - 08-Jan-2018¶
0.0.9 - 24-Nov-2017¶
Added¶
Updated¶
- use explicit version name: moban_file_spec_version so that version can be used by users. #10 Please note: moban_file_spec_version is reserved for future file spec upgrade. For now, all files are assumed to be ‘1.0’. When there comes a new version i.e. 2.0, new moban file based on 2.0 will have to include ‘moban_file_spec_version: 2.0’
0.0.8 - 18-Nov-2017¶
Added¶
- #8, verify the existence of custom template and configuration directories. default .moban.td, .moban.cd are ignored if they do not exist.
Updated¶
- Colorize error messages and processing messages. crayons become a dependency.
0.0.7 - 19-Jul-2017¶
0.0.6 - 16-Jun-2017¶
Added¶
- added ‘-f’ flag to force moban to template all files despite of .moban.hashes
Updated¶
- moban will not template target file in the situation where the changes occured in target file than in the source: the template file + the data configuration after moban has been applied. This new release will remove the change during mobanization process.