moban - 模板 Yet another jinja2 cli command for static text generation¶
Author: | C.W. |
---|---|
Issues: | http://github.com/moremoban/moban/issues |
License: | MIT |
Version: | 0.4.5 |
Generated: | Jul 08, 2019 |
moban brings the high performance template engine (JINJA2) for web into static text generation. It is used in pyexcel and coala project to keep documentation consistent across the documentations of individual libraries.
Our vision is: any template, any data. Our current architecture enables moban to plugin any python template engine: mako, handlebars, velocity, haml, slim and tornado and to plugin any data format: json and yaml. Please look at our issues. We have many more template engines and data format on the road map.
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¶
$ export HELLO="world"
$ moban "{{HELLO}}"
Warning: Both data.yml and /.../.moban.cd/data.yml does not exist
Warning: Attempting to use environment vars as data...
Templating {{HELLO}}... to moban.output
Templated 1 file.
$ cat moban.output
world
Or simply
$ HELLO="world" moban "{{HELLO}}"
A bit formal 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
Please note that data.yml will take precedence over environment variables.
the tutorial has more use cases.
Usage¶
usage: moban [-h] [-cd CONFIGURATION_DIR] [-c CONFIGURATION]
[-td [TEMPLATE_DIR [TEMPLATE_DIR ...]]] [-t TEMPLATE] [-o OUTPUT]
[-f] [-m MOBANFILE]
[template]
Yet another jinja2 cli command for static text generation
positional arguments:
template string templates
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. if not present, moban
will try to use environment vars as data
-td [TEMPLATE_DIR [TEMPLATE_DIR ...]], --template_dir [TEMPLATE_DIR [TEMPLATE_DIR ...]]
the directories for template file lookup
-t TEMPLATE, --template TEMPLATE
the template file. this overrides any targets
defined in a custom moban file
-o OUTPUT, --output OUTPUT
the output file
--template_type TEMPLATE_TYPE
the template type, default is jinja2
-f force moban to template all files despite of
.moban.hashes
--exit-code tell moban to change exit code
-m MOBANFILE, --mobanfile MOBANFILE
custom moban file
Exit codes¶
By default:
- 0 : no error
- 1 : error occured
With –exit-code:
- 0 : no changes
- 1 : has changes
- 2 : error occured
Built-in 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
repr¶
Returns a single quoted string in the templated file
Tutorial¶
Please clone the moban repository as the data mentioned in the tutorial are stored in examples folder.
- Level 1 Jinja2 on command line
- Level 2: template inheritance
- Level 3: data override
- Level 4: single command
- Level 5: custom configuration
- Level 6: Complex Configuration
- Level 7: Custom jinja filters, tests and globals
- Level 8: Pass a folder full of templates
- level 9: moban dependency as pypi package
- level 10: moban dependency as git repo
- Level 11: use handlebars
- Level 12: use template engine extensions
- Level 13: any data override any data
- Level 14: custom data loader
- Level 15: template copying becomes an action plugin in targets
- Level 16: group targets by their template type
- Level 17: force template type
- Level 18: User defined template types
- Level 19: select a group target to run
For more complex use case, please look at its usage in pyexcel project
Developer Guide¶
Change log¶
0.4.3 - 16.03.2019¶
0.4.2 - 08.03.2019¶
Added¶
Updated¶
- #180: No longer two statistics will be shown in v0.4.x. legacy copy targets are injected into a normal targets. cli target is made a clear priority.
- #244: version 0.4.2 is first version which would work perfectly on windows since 17 Nov 2018. Note that: file permissions are not used on windows. Why the date? because samefile is not avaiable on windows, causing unit tests to fail hence it lead to my conclusion that moban version between 17 Nov 2018 and March 2019 wont work well on Windows.
0.4.1 - 28.02.2019¶
0.4.0 - 20.02.2019¶
0.3.9 - 18-1-2019¶
0.3.8 - 12-1-2019¶
Updated¶
- #141: disable file permissions copy feature and not to check file permission changes on windows.
- #154: introduce first ever positional argument for string base template.
- #157: the exit code behavior changed. for backward compactibility please use –exit-code. Otherwise, moban will not tell if there is any changes.
0.3.7 - 6-1-2019¶
0.3.6 - 30-12-2018¶
0.3.5 - 10-12-2018¶
0.3.4 - 18-11-2018¶
Added¶
- global variables to store the target and template file names in the jinja2 engine
- moban-handlebars is tested to work well with this version and above
Updated¶
- Template engine interface has been clarified and documented
0.3.3 - 05-11-2018¶
Added¶
- alternative and expanded syntax for requires, so as to accomendate github submodule recursive
0.3.2 - 04-11-2018¶
Added¶
- requires shall support configuration dirs. In other words, configuration file could be stored in python package or git repository.
0.3.1 - 02-11-2018¶
0.3.0 - 27-18-2018¶
0.2.4 - 14-07-2018¶
0.2.3 - 10-07-2018¶
0.2.2 - 16-06-2018¶
0.2.1 - 13-06-2018¶
Updated¶
- templates using the same template engine will be templated as a group
- update lml dependency to 0.0.3
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.