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.

default_branch

The name of the default branch. This is “master” by default (source). But GitHub replaced “master” with “main” in October 2020 in order to “remove unnecessary references to slavery and replace them with more inclusive terms.” (source).

For newer GitHub repositories you must set this to main in your tasks.py. The variable is currently used only by the show-source.html template.

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.