Getting Started#

Install `doitoml`#

Use your python package manager of choice to install a release of doitoml:

PyPI

pip install doitoml

conda-forge

mamba install -c conda-forge doitoml

conda install -c conda-forge doitoml

This will install...

doitoml and its dependencies
- doit[toml]
- tomli (if you’re on python <3.11)

Configure `doit`#

Like many Python-based tools, doit prefers finding its configuration in pyproject.toml under the [tool.doit] prefix.

doitoml provide an entry point for doit.LOADER, which offers task discovery features from files. As an alternative, advanced users of dodo.py can use the Python API.

# pyproject.toml
[tool.doit]
loader = "doitoml"

Schema#

A partial schema for the doit and doitoml-relevant parts of pyproject.toml is available.

Note that this is fairly incomplete, and doesn’t work very well with community-based systems such as schemastore.org

Using the taplo language server, a pyproject.toml may declare a schema with either the standards-based $schema property:

"$schema" = "https://doitoml.rtfd.io/en/latest/_static/_pyproject.v0.schema.json"

…or the taplo-specific directive:

#:schema https://doitoml.rtfd.io/en/latest/_static/_pyproject.v0.schema.json

…or via explicit configuration.

Similarly, the package.json counterpart (which can’t configure doit) is available as:

{
    "$schema": "https://doitoml.rtfd.io/en/latest/_static/_jspackage.v0.schema.json"
}

Local Schema#

To get a local copy of the schema which includes custom schema as defined by first- and third-party addons, use python -m doitoml.schema.dump.

This could be combined with a community-maintained schema such as schemastore.org to handle other well-known tools.

!python -m doitoml.schema.dump --help

usage: doitoml-schema-dump [-h] [-t {pyproject.toml,package.json}] [-o OUTPUT]
                           [-f {json,yaml,toml}]

options:
  -h, --help            show this help message and exit
  -t {pyproject.toml,package.json}, --type {pyproject.toml,package.json}
                        target file container
  -o OUTPUT, --output OUTPUT
                        the output file (or stdout)
  -f {json,yaml,toml}, --format {json,yaml,toml}
                        format to write

Write Tasks#

Tasks are the most important part of using doit. These are written in the [tool.doitoml.tasks] prefix. For readability, it’s encouraged to fully write out tasks in their own sections.

# pyproject.toml
[tool.doit]
loader = "doitoml"

[tool.doitoml.tasks.hello]
actions = ['echo "hello world"']

Note

While the above, cross-platform shell task is simple and powerful, this pattern inroduces a number of risks around shell escaping. Keep reading for more about other kinds of tasks.

Parts of tasks#

Even in vanilla doit, there are a large number of configurable options. Few tasks will need close to all of them, but a few are worth pointing out:

field	kind	description
`actions`	list of (strings or list of strings)	the raw shell command or shell tokens
`targets`	list of paths	files created or modified by a task
`file_dep`	list of paths	files that, when changed, will cause a task to be run
`task_dep`	list of fully-qualified task ids	the names (with optional `` wildcards) of any other* tasks that need to have been run before a task
`doc`	string	a text description of a task
`meta`	dict	a dictionary of extra values, not used directly by `doit`
`uptodate`	list of (string, bool or dict)	update checkers that complement `file_dep` and `task_dep`

See the cheatsheet for more.

Use `doit`#

Run Tasks#

By default, doit [run] will run all known tasks.

doit

List Tasks#

Now you are ready to start working with your tasks:

doit list --all --status

This will print out the names of all runnable tasks, and whether they have been (or need to be) run.

Inspect Tasks#

With the name of the task from list, you can learn more about a specific task.

doit info hello

This prints out more information about the task.

Extend with `doitoml`#

Now that some tasks are running, doitoml provides some tools to help keep your task definitions short and reusable.

section	description
`env`	environment variables
`paths`	reusable paths
`tokens`	command shell tokens
`templates`	data-driven templates

`paths`#

Paths are the most robust way to manage the relationships between tasks. doitoml.paths allow for defining paths which can be reused in multiple tasks.

Simple paths#

The simplest path is just a list of strings, treated as relative paths to the file that defines them.

[tool.doitoml.paths]
hello = ["hello.txt"]
hola = ["es/hola.txt"]

Note

Only POSIX-style slashes / are supported as \ is used as an escape character by most syntaxes.

Reusing paths#

Paths can be reused in other paths, with the :: syntax:

[tool.doitoml.paths]
hello = ["hello.py"]
greetings = ["::hello"]

And in token-type tasks:

[tool.doitoml.tasks.hello]
actions = [["python", "::hello"]]

Note

A number of other path patterns are available, and can also be extended with new syntax.

Referencing `env`#

Paths can also reference environment variables.

[tool.doitoml.env]
MY_NUMBER = "42"

[tool.doitoml.paths]
my_build = "my-project-${MY_NUMBER}.zip"

`env`#

Environment variables are a cross-platform, cross-language way to provide consistent data across many processes.

[tool.doitoml.env]
MY_DATA = "some-data"
MY_OTHER_DATA = "more-of-${MY_DATA}"

Note

Only the POSIX-style ${ENV_VAR} syntax is supported: $ENV_VAR and %ENV_VAR% have no particular meaning.

`tokens`#

The tokens section is useful for defining frequently-reused strings, and share the same namespace as paths.

[tool.doitoml.tokens]
py = ["python3"]
py_c = ["::py", "-c"]
py_m = ["::py", "-m"]

These are useful for keeping task actions short.

[tool.doitoml.tasks.hello]
actions = [["::py_c", "print('hello')"]]

Summary#

Building declarative tasks for doit with doitoml makes it easier to automate simple, software-driven tasks in a predictable, reproducible way, but this barely scratches the surface of what is possible.

Hint

For an overview, see the cheatsheet.

Additionally, see more in-depth guides:

TODO

Defining tasks in multiple files

Extending doitoml

Data-driven projects