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 (unless you specified -b or --batch).

The release will fail if the project has previously been published on PyPI with the same version.

If you specified -r or --branch (and revision_control_system is 'git'), create and push a version branch “vX.Y.Z”.

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.

flags:

• --list

  Lists all the required packages from all of the installed Plugin using get_requirements and writes them into requirements-install.txt file.

  Also, installs the required packages.

  Equivalent of running:

  $ manage.py install && manage.py install --list
  

• --list-only

  Lists all the packages as –list does and does not install the packages. Equivalent of running:

  $ manage.py install --list
  

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.

inv update-fixtures

Update fixtures that scrape from external data sources like wikidata.

Runs the fixtures_updater function.

Project configuration settings

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

blog_root

The doctree where inv blog should create blog entries.

Default value is root_dir / 'docs'.

build_dir_name

Where inv bd should store the generated html files.

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

project_name

The nickname to use for this project.

Default value is str(root_dir.name)

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

Where to store temporary files for inv dist.

Default value is root_dir / '.pypi_cache'.

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.

It is used to build multilingual websites. Caution: this is tricky.

The first specified language is the default language, whose source tree is docs. For every remaining language xx there must be a source tree named xxdocs. These non-default source trees will be built below the default source tree.

When selectable_languages is [‘en’, ‘de’] and doc_trees has its default value [‘docs’], then atelier expects two Sphinx source trees docs and dedocs. The output of docs will be under the normal location docs/.build, but the output of dedocs will be under docs/.build/de.

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.

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.