runner: compute environment changes when desired

JobRunner._get_script_env can now be asked to compute
the changes to the environment rather then a full modified copy.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
runner: use pkexec to run jobs as different users

[work in progress/needs testing]
[work in progress/stops current integration tests from working]
[work in progress/needs a policy file, maybe]

This patch adds support for running jobs as another user by invoking
pkexec and env to construct the desired environment while running
as another user.

This approach works but is probably impossible to secure.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
vagrant: install policykit-1 while provisioning

The pkexec(1) program is distributed in the policykit-1 package.
This is a new dependency of plainbox.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: reformat all module headers

This makes each module's docstring a valid documentation header for
that module itself.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: fix some invalid ReST markup

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: assorted docstrings

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: remove broken syntax

sphinx complained about this section. It is not essential so it can be
removed.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: add 'usage' chapter
docs: add glossary chapter

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: add changelog chapter

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: add dev chapter

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: add dev/intro chapter

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: add dev/architecture chapter

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
docs: add dev/reference chapter
docs: rework front page

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
runner: PEP-8 fix

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
depmgr: use ReST syntax for DependencySolver docstrings

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
session: PEP8 fixes

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
session: remove inaccurate docstring

The docstring wrongly claims that readiness_inhibitor_list or result
may be None which is never the case

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
session: large ReST changes to SessionState docstring

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>