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 indoc_trees
. The exact options for sphinx-build depend also ontolerate_sphinx_warnings
anduse_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
andlanguages
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 unlikegit 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 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 bydemo_projects
.
- inv prep¶
Prepare a test run. This runs
prep
on every demo project defined bydemo_projects
.It is not launched automatically by
inv test
orinv 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
orpy.test
or `` tox`` (depending on whether your project has apytest.ini
ortox.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
filesAll
__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
.
-
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 thesetup.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 fromdoc_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 fromdoc_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 intasks.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 intasks.py
.
-
use_dirhtml
¶ Whether sphinx-build should use
dirhtml
instead of the defaulthtml
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
orinv bd
, they must have been initialized withinv 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
wheninv prep
is invoked. The default value ismanage.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.