User guide¶
Installation¶
$ pip install mr.bob
Usage¶
Once you install mr.bob, the mrbob command is available:
$ mrbob --help
usage: mrbob [-h] [-O TARGET_DIRECTORY] [-v] [-c CONFIG] [-V] [-l] [-w] [-n]
[-q]
[template]
Filesystem template renderer
positional arguments:
template Template name to use for rendering. See http://mrbob.r
eadthedocs.org/en/latest/userguide.html#usage for a
guide to template syntax
optional arguments:
-h, --help show this help message and exit
-O TARGET_DIRECTORY, --target-directory TARGET_DIRECTORY
Where to output rendered structure. Defaults to
current directory
-v, --verbose Print more output for debugging
-c CONFIG, --config CONFIG
Configuration file to specify either [mr.bob] or
[variables] sections
-V, --version Display version number
-l, --list-questions List all questions needed for the template
-w, --remember-answers
Remember answers to .mrbob.ini file inside output
directory
-n, --non-interactive
Don't prompt for input. Fail if questions are required
but not answered
-q, --quiet Suppress all but necessary output
By default, the target directory is the current folder. The most basic use case is rendering a template from a relative folder:
$ mrbob ../template_folder/
Or from a package:
$ mrbob some.package:template_folder/
Or from a downloaded zip file:
$ mrbob https://example.com/templates/mytemplate.zip
Or from a relative path in a zip file:
$ mrbob https://github.com/iElectric/mr.bob/archive/master.zip#mr.bob-master/mrbob/template_sample
Sample template to try out¶
$ mrbob mrbob:template_sample/
Welcome to mr.bob interactive mode. Before we generate directory structure, some questions need to be answered.
Answer with a question mark to display help.
Value in square brackets at the end of the questions present default value if there is no answer.
--> How old are you? [24]:
--> What is your name?: Foobar
--> Enter password:
Generated file structure at /current/directory/
Listing all questions needed to have corresponding variable for a template¶
$ mrbob --list-questions mrbob:template_sample/
author.age.default = 24
author.age.help = We need your age information to render the template
author.age.question = How old are you?
author.name.question = What is your name?
author.name.required = True
author.password.command_prompt = getpass:getpass
author.password.question = Enter password
Remember answers to a config file¶
Running:
$ mrbob --remember-answers -O new_dir mrbob:template_sample/
...
When everything is done, all answers are stored in new_dir/.mrbob.ini so later you reuse them:
$ mrbob --config new_dir/.mrbob.ini -O new_dir another_template/
...
Using non-interactive mode¶
Sometimes you might want to automate a script and use mrbob. It is wise to tell mrbob to not prompt for any input. mrbob will use given answers and defaults if answers are missing. In case a question is required and doesn’t have a default, error will be thrown.
Configuration¶
Configuration is done with .ini style files. There are two sections for configuration: :term:mr.bob and :term:variables.
Example of global config file ~/.mrbob or command line parameter mrbob --config foo.ini.
[mr.bob]
verbose = True
[variables]
author.name = Domen Kožar
author.email = domen@dev.si
Specifying answers¶
To answer some questions from a config file instead of interactively. Given me.ini:
[variables]
author.name = Domen Kožar
author.email = domen@dev.si
author.age = 24
do:
$ mrbob --config me.ini mrbob:template_sample/
Specifying defaults¶
Sometimes you might want to override defaults for a template. Given me.ini:
[defaults]
author.name = Domen Kožar
author.email = domen@dev.si
author.age = 24
do:
$ mrbob --config me.ini mrbob:template_sample/
mrbob will as you questions but default values will be also taken from config file.
Remote configuration¶
Config file can also be loaded from a remote location:
$ mrbob --config https://raw.github.com/iElectric/mr.bob/master/mrbob/tests/example.ini mrbob:template_sample/
Configuration inheritance¶
Configuration can be specified in multiple ways. See flow of mr.bob on the documentation front page to know how options are preferred.
Nesting variables into namespaces called groups¶
All variables can be specified in namespaces, such as author.name. Currently namespaces don’t do anything special besides providing readability.
mr.bob section reference¶
Parameter | Default | Explanation |
---|---|---|
ignored_files | No patterns | Multiple Unix-style patterns to specify which files should be ignored: for instance, to ignore Vim swap files, specify *.swp |
ignored_directories | No patterns | Multiple Unix-style patterns to specify which directories should be ignored: for instance, to ignore a Git directory, specify .git |
non_interactive | False | Don’t prompt for input. Fail if questions are required but not answered |
quiet | False | Don’t output anything except necessary |
remember_answers | False | Write answers to .mrbob.ini file inside output directory |
verbose | False | Output more information, useful for debugging |
Collection of community managed templates¶
You are encouraged to use the bobtemplates.something Python egg namespace to write templates and contribute them to this list by making a pull request.