inv tasks defined by atelier

This document describes the tasks and configuration settings for inv provided by atelier.

Note: code examples in this document use the atelier project

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

Tasks

Following are the tasks you get when you import atelier.invlib into your tasks.py file.

Commands for documenting

inv bd

Build docs. Build all Sphinx HTML doctrees for this project.

This runs inv readme, followed by sphinx-build html in every directory defined in doc_trees. The exact options for sphinx-build depend also on tolerate_sphinx_warnings and use_dirhtml.

inv pd

Publish docs. Upload docs to public web server.

inv blog

Edit today’s blog entry, create an empty file if it doesn’t yet exist.

inv readme

Generate or update README.txt or README.rst file from SETUP_INFO.

Commands for internationalization

inv mm

(“make messages”)

Extracts translatable messages from both code and userdocs, then initializes and updates all catalogs. Needs locale_dir and languages to be set.

Commands for deployment

inv ci

Checkin and push to repository, using today’s blog entry as commit message.

Asks confirmation before doing so.

Does nothing in a project whose revision_control_system is None.

In a project whose revision_control_system is 'git' it checks whether the repository is dirty (i.e. has uncommitted changes) and returns without asking confirmation if the repo is clean. Note that unlike git status, this check does currently not (yet) check whether my branch is up-to-date with ‘origin/master’.

inv reg

Register this project (and its current version) to PyPI.

inv sdist

Write a source distribution archive to your sdist_dir.

inv release

Upload the source distribution archive previously created by inv sdist to PyPI, i.e. publish an official version of your package.

Before doing anything, it shows the status of your local repository (which should be clean) and a summary of the project status on PyPI. It then asks a confirmation. The release will fail if the project has previously been published on PyPI with the same version.

If revision_control_system is 'git', create and push a version branch “vX.Y.Z”. This step can be skipped by specifying --nobranch.

This command requires that twine is installed.

Commands for testing

inv install

Install Python requirements. Runs install on every demo project defined by demo_projects.

inv prep

Prepare a test run. This runs prep on every demo project defined by demo_projects.

It is not launched automatically by inv test or inv bd because it can take some time and is not always necessary.

inv test

Run the test suite of this project.

This is a shortcut for either python setup.py test or py.test or `` tox`` (depending on whether your project has a pytest.ini or tox.ini files or not and ).

inv cov

Create a coverage report.

You can configure the command to use by setting coverage_command.

inv test_sdist

Creates and activates a temporay virtualenv, installs your project and runs your test suite.

• creates and activates a temporay virtualenv,

• calls pip install --no-index -f <env.sdist_dir> <prjname>

• runs python setup.py test

• removes temporary files.

Assumes that you previously did inv sdist of all your projects related to this project.

Miscellaneous commands

inv clean

Remove temporary and generated files:

• Sphinx .build files

• All __pycache__ directories.

• additional files specified in cleanable_files

Unless option --batch is specified, ask for an interactive user confirmation before removing these files.

inv ct

Display a list of commits in all projects during the last 24 hours.

inv check

Perform an integrity check for this project. Experimental.

Configuration settings

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

locale_dir

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

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

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.

docs_rsync_dest

A Python template string which 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).

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 atelier.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.

use_dirhtml

Whether sphinx-build should use dirhtml instead of the default html builder.

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.

selectable_languages

A tuple or list of language codes for which there is a doctree. Experimental.

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 Django demo projects included in this project.

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

Django demo projects are used by the test suite and the Sphinx documentation. Before running inv test or inv bd, they must have been initialized with inv prep.

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

A shell command to be run in every demo project when inv prep is invoked. The default value is manage.py prep --noinput --traceback.

Default value is empty.

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

test_command

The command to be run by inv test.

Default value is python -m unittest discover -s tests.

>>> prj.get_xconfig('test_command')
'python -m unittest discover -s tests'

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

build_docs_command

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'