Project configuration settings

The following settings are available in your tasks.py when it uses atelier.invlib.

Code examples in this document use the atelier project

>>> from atelier.projects import get_project_from_module
>>> prj = get_project_from_module('atelier')

Blogging

blog_root

The doctree where inv blog should create blog entries.

Default value is root_dir / 'docs'.

multiple_blog_entries_per_day

Whether blog entries are named yyyy/mmdd.rst (default) or yyyy/mmdd_HHMM.rst (support multiple blog entries per day).

General

project_name

The nickname to use for this project.

Default value is str(root_dir.name)

editor_command

A string with the command name of your text editor. Example:

editor_command = "emacsclient -n {0}"

The {0} will be replaced by the filename.

Used by inv blog.

Note that this must be a non waiting command, i.e. which launches the editor on the specified file in a new window and then returns control to the command line without waiting for that new window to terminate.

Internationalization

locale_dir

The name of the directory where inv mm et al should write their catalog files.

Deploy

sdist_dir

The template for the local directory where inv sdist should store the packages. Any string {prj} in this template will be replaced by the projects Python name. The resulting string is passed as the –dist-dir option to the setup.py sdist command.

pypi_dir

Where to store temporary files for inv dist.

Default value is root_dir / '.pypi_cache'.

Settings for rstgen

The atelier config also forwards the rstgen settings use_dirhtml, selectable_languages and public_url.

Miscellaneous

build_dir_name

Where inv bd should store the generated html files.

Default value is '.build', but e.g. ablog needs '_build'.

docs_rsync_dest

A Python template string that defines the rsync destination for publishing your projects documentation.

Used by inv pd.

Example:

env.docs_rsync_dest = 'luc@example.org:~/public_html/{prj}_{docs}'

The {prj} in this template will be replaced by the internal name of this project, and {{docs}} by the name of the doctree (taken from doc_trees).

For backward compatibility the following (deprecated) template is also still allowed:

env.docs_rsync_dest = 'luc@example.org:~/public_html/%s'

The %s in this template will be replaced by a name xxx_yyy, where xxx is the internal name of this project and yyy the name of the doctree (taken from doc_trees).

rsync_command

The Python template for the command to run for uploading a build doctree to the docs_rsync_dest).

Used by inv pd.

Default value:

rsync_command = "rsync -e ssh -r --verbose --progress --delete "
    "--times --omit-dir-times --exclude .doctrees ./ {dest_url}")

Where {dest_url} is the value of docs_rsync_dest.

srcref_url

The URL template to use for srcref roles.

If the project has a main package which has an attribute srcref_url, then this value will be used.

intersphinx_urls

A dict which maps doctree names to the URL where they are published. This is used when this project’s documentation is added to a doctree using rstgen.sphinxconf.interproject.

If the project has a main package which defines an attribute intersphinx_urls, then this will override any value define in tasks.py.

doc_trees

A list of directory names (relative to your project directory) containing Sphinx document trees.

Default value is ['docs']

>>> prj.get_xconfig('doc_trees')
['docs']

If the project has a main package which defines an attribute doc_trees, then this will override any value define in tasks.py.

cleanable_files

A list of wildcards to be cleaned by inv clean.

tolerate_sphinx_warnings

Whether sphinx-build should tolerate warnings.

languages

A list of language codes for which gettext translations and userdocs are being maintained. Used by:cmd:inv mm.

revision_control_system

The revision control system used by your project. Allowed values are ‘git’, ‘hg’ or None. Used by inv ci, inv release, per_project.

use_mercurial

No longer used. Use revision_control_system instead.)

demo_projects

The list of demo projects defined in this repository.

Every item of this list is the full Python path of a package that must have a manage.py file.

prep_command

A shell command to be run in in the project’s root directory when inv prep is invoked. The default value is empty.

Default value is empty.

>>> prj.get_xconfig('prep_command')
''

demo_prep_command

The shell command to be run in every demo project when inv prep is invoked.

The default value is manage.py prep --noinput --traceback, that is, it runs pm prep.

>>> prj.get_xconfig('demo_prep_command')
'manage.py prep --noinput --traceback'

test_command

The command to be run by inv test.

Default value runs python -m unittest discover -s tests (unless there is no directory named tests, in which case it does nothing):

>>> prj.get_xconfig('test_command')
'if [ -d tests ]; then python -m unittest discover -s tests; fi'

The command will always be invoked from the projects root dir.

make_docs_command

An optional command to run when inv bd is invoked. It can be used for generating .rst files even before sphinx-build is run.

Default value is an empty string.

build_docs_command

Removed since 20210425. The command to run by inv bd.

Default value is an empty string.

If this is empty, the default behaviour is to run sphinx-build in each doc_trees.

coverage_command

The command to be run under coverage by inv cov.

Default value runs inv prep, then inv test then inv clean -b and finally inv bd.

>>> prj.get_xconfig('coverage_command')
'`which invoke` prep test clean --batch bd'

fixtures_updater

A callable that will be called when you say inv update-fixtures.