Skip to content
Commits on Source (10)
......@@ -5,7 +5,7 @@ mandir = $(sharedir)/man
man1dir = $(mandir)/man1
man8dir = $(mandir)/man8
libdir = $(prefix)/lib
docdir = $(prefix)/share/doc/piuparts/
docdir = $(prefix)/share/doc/piuparts
site27 = $(libdir)/python2.7/dist-packages
htdocsdir = $(sharedir)/piuparts/htdocs
etcdir = $(prefix)/etc
......@@ -23,7 +23,7 @@ endif
SCRIPTS_TEMPLATES = $(wildcard *.in master-bin/*.in slave-bin/*.in conf/*.in)
SCRIPTS_PYTHON_BINARY = $(wildcard *.py master-bin/*.py slave-bin/*.py)
SCRIPTS_GENERATED = $(SCRIPTS_TEMPLATES:.in=) $(SCRIPTS_PYTHON_BINARY:.py=)
DOCS_GENERATED = piuparts.1 piuparts.1.html piuparts_slave_run.8 piuparts_slave_join.8 piuparts_slave_stop.8 README.html README_server.html
DOCS_GENERATED = piuparts.1 piuparts_slave_run.8 piuparts_slave_join.8 piuparts_slave_stop.8 docs/build
define placeholder_substitution
sed -r \
......@@ -63,31 +63,63 @@ build-master-stamp:
build-doc: $(DOCS_GENERATED)
README.html: README.txt
a2x --copy -a toc -a toclevels=3 -f xhtml -r /etc/asciidoc/ README.txt
docs/build: docs/build
sphinx-build docs/ docs/build/
README_server.html: README_server.txt
a2x --copy -a toc -a toclevels=3 -f xhtml -r /etc/asciidoc/ README_server.txt
piuparts.1: docs/piuparts/piuparts.1.txt
sphinx-build -b man -c docs/piuparts/ docs/piuparts/ ./
piuparts.1: piuparts.1.txt
a2x -f manpage piuparts.1.txt
piuparts_slave_run.8: docs/piuparts_slave_run/piuparts_slave_run.8.txt
sphinx-build -b man -c docs/piuparts_slave_run/ docs/piuparts_slave_run/ ./
piuparts_slave_run.8: piuparts_slave_run.8.txt
a2x -f manpage piuparts_slave_run.8.txt
piuparts_slave_join.8: piuparts_slave_join.8.txt
a2x -f manpage piuparts_slave_join.8.txt
piuparts_slave_stop.8: piuparts_slave_stop.8.txt
a2x -f manpage piuparts_slave_stop.8.txt
piuparts.1.html: piuparts.1.txt
a2x --copy -f xhtml piuparts.1.txt
piuparts_slave_join.8: docs/piuparts_slave_join/piuparts_slave_join.8.txt
sphinx-build -b man -c docs/piuparts_slave_join/ docs/piuparts_slave_join/ ./
piuparts_slave_stop.8: docs/piuparts_slave_stop/piuparts_slave_stop.8.txt
sphinx-build -b man -c docs/piuparts_slave_stop/ docs/piuparts_slave_stop/ ./
install-doc: build-stamp
# txt
install -d $(DESTDIR)$(docdir)/
install -m 0644 README.txt README.html README_server.txt README_server.html docbook-xsl.css $(DESTDIR)$(docdir)/
install -m 0644 docs/README.txt docs/README_server.txt $(DESTDIR)$(docdir)/
# html
install -d $(DESTDIR)$(docdir)/html/
install -m 0644 docs/build/*.html $(DESTDIR)$(docdir)/html/
install -m 0644 docs/build/searchindex.js $(DESTDIR)$(docdir)/html/
install -m 0644 docs/build/objects.inv $(DESTDIR)$(docdir)/html/
install -d $(DESTDIR)$(docdir)/html/_static/
install -m 0644 docs/build/_static/* $(DESTDIR)$(docdir)/html/_static
install -d $(DESTDIR)$(docdir)/html/piuparts/
install -m 0644 docs/build/piuparts/index.html $(DESTDIR)$(docdir)/html/piuparts/
install -m 0644 docs/build/piuparts/piuparts.1.html $(DESTDIR)$(docdir)/html/piuparts/
install -d $(DESTDIR)$(docdir)/html/piuparts_slave_run/
install -m 0644 docs/build/piuparts_slave_run/index.html $(DESTDIR)$(docdir)/html/piuparts_slave_run/
install -m 0644 docs/build/piuparts_slave_run/piuparts_slave_run.8.html $(DESTDIR)$(docdir)/html/piuparts_slave_run/
install -d $(DESTDIR)$(docdir)/html/piuparts_slave_join/
install -m 0644 docs/build/piuparts_slave_join/index.html $(DESTDIR)$(docdir)/html/piuparts_slave_join/
install -m 0644 docs/build/piuparts_slave_join/piuparts_slave_join.8.html $(DESTDIR)$(docdir)/html/piuparts_slave_join/
install -d $(DESTDIR)$(docdir)/html/piuparts_slave_stop/
install -m 0644 docs/build/piuparts_slave_stop/index.html $(DESTDIR)$(docdir)/html/piuparts_slave_stop/
install -m 0644 docs/build/piuparts_slave_stop/piuparts_slave_stop.8.html $(DESTDIR)$(docdir)/html/piuparts_slave_stop/
install -d $(DESTDIR)$(docdir)/html/
install -m 0644 docs/build/*.html $(DESTDIR)$(docdir)/html/
install -m 0644 docs/build/searchindex.js $(DESTDIR)$(docdir)/html/
install -m 0644 docs/build/objects.inv $(DESTDIR)$(docdir)/html/
install -d $(DESTDIR)$(docdir)/html/_static/
install -m 0644 docs/build/_static/* $(DESTDIR)$(docdir)/html/_static
install -d $(DESTDIR)$(docdir)/html/piuparts/
install -m 0644 docs/build/piuparts/index.html $(DESTDIR)$(docdir)/html/piuparts/
install -m 0644 docs/build/piuparts/piuparts.1.html $(DESTDIR)$(docdir)/html/piuparts/
install -d $(DESTDIR)$(docdir)/html/piuparts_slave_run/
install -m 0644 docs/build/piuparts_slave_run/index.html $(DESTDIR)$(docdir)/html/piuparts_slave_run/
install -m 0644 docs/build/piuparts_slave_run/piuparts_slave_run.8.html $(DESTDIR)$(docdir)/html/piuparts_slave_run/
install -d $(DESTDIR)$(docdir)/html/piuparts_slave_join/
install -m 0644 docs/build/piuparts_slave_join/index.html $(DESTDIR)$(docdir)/html/piuparts_slave_join/
install -m 0644 docs/build/piuparts_slave_join/piuparts_slave_join.8.html $(DESTDIR)$(docdir)/html/piuparts_slave_join/
install -d $(DESTDIR)$(docdir)/html/piuparts_slave_stop/
install -m 0644 docs/build/piuparts_slave_stop/index.html $(DESTDIR)$(docdir)/html/piuparts_slave_stop/
install -m 0644 docs/build/piuparts_slave_stop/piuparts_slave_stop.8.html $(DESTDIR)$(docdir)/html/piuparts_slave_stop/
# manpages
install -d $(DESTDIR)$(man1dir)
install -m 0644 piuparts.1 $(DESTDIR)$(man1dir)/
gzip -9fn $(DESTDIR)$(man1dir)/piuparts.1
......@@ -96,7 +128,6 @@ install-doc: build-stamp
gzip -9fn $(DESTDIR)$(man8dir)/piuparts_slave_run.8
gzip -9fn $(DESTDIR)$(man8dir)/piuparts_slave_join.8
gzip -9fn $(DESTDIR)$(man8dir)/piuparts_slave_stop.8
install -m 0644 piuparts.1.html $(DESTDIR)$(docdir)/
install-conf: build-stamp
install -d $(DESTDIR)$(etcdir)/piuparts
......@@ -175,8 +206,8 @@ check:
clean:
rm -f build-stamp
rm -f build-master-stamp
rm -f $(DOCS_GENERATED)
rm -f piuparts.1.xml README.xml README_server.xml docbook-xsl.css piuparts.html
rm -fr $(DOCS_GENERATED)
rm -fr .doctrees/
rm -f *.pyc piupartslib/*.pyc master-bin/*.pyc slave-bin/*.pyc tests/*.pyc
rm -f $(SCRIPTS_GENERATED)
$(RM) helpers/debiman-piuparts-distill/debiman-piuparts-distill
......
......@@ -7,7 +7,6 @@ Priority: optional
Standards-Version: 4.4.0
Rules-Requires-Root: no
Build-Depends:
asciidoc,
debhelper-compat (= 11),
dh-python,
python (>= 2.7),
......@@ -19,8 +18,8 @@ Build-Depends:
python-yaml,
python-mox3,
python-lzma,
python-sphinx,
golang-any,
xmlto,
Build-Depends-Indep:
git,
Homepage: https://piuparts.debian.org
......@@ -35,6 +34,7 @@ Depends:
# keep this list in sync with piuparts-slave-from-git-deps
debootstrap (>= 1.0.89~),
debsums (>= 2.2.2~),
libjs-sphinxdoc,
lsb-release,
lsof,
mount,
......@@ -160,6 +160,7 @@ Depends:
# this list is synced from piuparts
debootstrap (>= 1.0.89~),
debsums (>= 2.2.2~),
libjs-sphinxdoc,
lsb-release,
lsof,
mount,
......
README_server.txt
README_pejacevic.txt
docs/README_server.txt
docs/README_pejacevic.txt
Document: piuparts
Title: Piuparts Manual
Author: Holger
Abstract: This manual describes what Piuparts is, and how it can be used.
Section: System/Package Management
Format: HTML
Index: /usr/share/doc/piuparts/html/index.html
Files: /usr/share/doc/piuparts/html/*.html
README.txt
README.html
piuparts.1.html
docbook-xsl.css
docs/README.txt
debian/tmp/usr/share/doc/piuparts/html/
/usr/share/javascript/sphinxdoc/1.0/jquery.js usr/share/doc/piuparts/html/_static/jquery.js
/usr/share/javascript/sphinxdoc/1.0/underscore.js usr/share/doc/piuparts/html/_static/underscore.js
/usr/share/javascript/sphinxdoc/1.0/doctools.js usr/share/doc/piuparts/html/_static/doctools.js
/usr/share/javascript/sphinxdoc/1.0/searchtools.js usr/share/doc/piuparts/html/_static/searchtools.js
piuparts README
---------------
.. raw:: html
<style> .blue {color:navy} </style>
.. role:: blue
.. _top1:
README
======
Author: Lars Wirzenius
Email: <liw@iki.fi>
......@@ -8,7 +17,8 @@ After reading this README you probably also want to have a look
at the piuparts manpage, to learn about the available options.
But read this document first!
== Introduction
:blue:`Introduction`
^^^^^^^^^^^^^^^^^^^^
piuparts is a tool for testing that .deb packages can be
installed, upgraded, and removed without problems. The
......@@ -24,16 +34,17 @@ since the Lenny release in 2009, though responsible maintainers
run piuparts locally before uploading packages to the archive.
== How to use piuparts in 5 minutes
:blue:`How to use piuparts in 5 minutes`
=== Basic Usage
:blue:`Basic Usage`
^^^^^^^^^^^^^^^^^^^
Testing your packages with piuparts is as easy as typing at the
console prompt:
console prompt:::
piuparts sm_0.6-1_i386.deb
----
# piuparts sm_0.6-1_i386.deb
----
Note that in order to work, piuparts has to be executed as user
root, so you need to be logged as root or use 'sudo'.
......@@ -42,30 +53,29 @@ This will create a sid chroot with debootstrap, where it'll test
your package.
If you want to test your package in another release, for example,
testing, you can do so with:
testing, you can do so with:::
----
# piuparts ./sm_0.6-1_i386.deb -d testing
----
By default, this will read the first mirror from your
'/etc/apt/sources.list' file. If you want to specify a different
mirror you can do it with the option '-m':
mirror you can do it with the option '-m':::
----
# piuparts ./sm_0.6-1_i386.deb -m http://ftp.de.debian.org/debian
----
It's possible to use -d more than once. For example, to do a first
installation in stable, then upgrade to testing, then upgrade to
unstable and then upgrade to the local package use this:
unstable and then upgrade to the local package use this:::
----
# piuparts -d stable -d testing -d unstable ./sm_0.6-1_i386.deb
----
=== Some tips
:ref:`top <top1>`
:blue:`Some tips`
^^^^^^^^^^^^^^^^^
piuparts also has a manpage, where all available options are explained.
......@@ -77,47 +87,48 @@ Piuparts has the option of using a tarball as the contents of the
initial chroot, instead of building a new one with debootstrap. A
easy way to use this option is use a tarball created with
pbuilder. If you are not a pbuilder user, you can create this
tarball with the command (again, as root):
tarball with the command (again, as root):::
----
# pbuilder --create
----
then you only have to remember to update this tarball with:
----
then you only have to remember to update this tarball with:::
# pbuilder --update
----
To run piuparts using this tarball:
----
To run piuparts using this tarball:::
# piuparts -p ./sm_0.6-1_i386.deb
----
If you want to use your own pre-made tarball:
----
If you want to use your own pre-made tarball:::
# piuparts --basetgz=/path/to/my/tarball.tgz ./sm_0.6-1_i386.deb
----
Piuparts also has the option of using a tarball as the contents
of the initial chroot, instead of building a new one with
pbuilder. You can save a tarball for later use with the '-s'
('--save') piuparts option. Some people like this, others prefer
('*-*-save') piuparts option. Some people like this, others prefer
to only have to maintain one tarball. Read the piuparts manpage
about the '-p', '-b' and '-s' options
While pbuilder itself supports using cdebootstrap, this is not
fully supported by piuparts: You will need to use debootstrap
or use the '--warn-on-debsums-errors' option for piuparts and then
or use the '*-*-warn-on-debsums-errors' option for piuparts and then
you will still see spurious warnings in the log.
=== Piuparts tests
:ref:`top <top1>`
:blue:`Piuparts tests`
^^^^^^^^^^^^^^^^^^^^^^
By default, piuparts does two tests:
. Installation and purging test.
. Installation, upgrade and purging tests.
The first test installs the package in a minimal chroot, removes
......@@ -127,11 +138,15 @@ version (deb files given to piuparts in the input), removes and
purges.
If you only want to perfom the first test, you can use the
option: '--no-upgrade-test'
option: '*-*-no-upgrade-test'
:ref:`top <top1>`
=== Testing packages in the config-files-remaining state
:blue:`Testing packages in the config-files-remaining state`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The --install-remove-install option modifies the three piuparts
The *-*-install-remove-install option modifies the three piuparts
tests in order to test package installation while config files
from a previous installation are remaining, but the package itself
was removed inbetween.
......@@ -139,21 +154,26 @@ This exercises different code paths in the maintainer scripts.
. Installation and purging test: install, remove, install again
and purge.
. Installation, upgrade and purging test: install the old version,
remove, install the new version and purge.
. Distupgrade test: install the version from the first
distribution, remove, distupgrade to the last distribution,
install the new version.
=== Analyzing piuparts results
:ref:`top <top1>`
:blue:`Analyzing piuparts results`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When piuparts finishes all the tests satisfactorily, you will get
these lines as final output:
these lines as final output:::
----
0m39.5s INFO: PASS: All tests.
0m39.5s INFO: piuparts run ends.
----
Anyway, it is a good idea to read the whole log in order to
discover possible problems that did not stop the piuparts
......@@ -163,11 +183,15 @@ If you do not get those lines, piuparts has failed during a test.
The latest lines should give you a pointer to the problem with
your package.
== Custom scripts with piuparts
:ref:`top <top1>`
:blue:`Custom scripts with piuparts`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can specify several custom scripts to be run inside piuparts.
You have to store them in a directory and give it as argument to
piuparts: '--scriptsdir=/dir/with/the/scripts'
piuparts: '*-*-scriptsdir=/dir/with/the/scripts'
This option can be given multiple times. The scripts from all
directories will be merged together (and later ones may overwrite
earlier scripts with the same filename).
......@@ -194,17 +218,24 @@ Depending on the current test, the variable PIUPARTS_TEST is set
to
. 'install' (installation and purging test),
. 'upgrade' (installation, upgrade and purging tests) or
. 'distupgrade'.
During the 'upgrade' and 'distupgrade' tests, the variable
PIUPARTS_PHASE is set to one of the following values:
. 'install' while initially installing the packages from the
repository,
. 'upgrade' when upgrading to the .debs,
. 'distupgrade' while reinstalling the packages after
'apt-get dist-upgrade' to ensure they were not removed accidently
During the 'install' test, the PIUPARTS_PHASE variable is set to
'install'.
......@@ -216,13 +247,13 @@ The following prefixes for scripts are recognized:
'post_chroot_unpack' - after the chroot has been unpacked/debootrapped.
Before the chroot gets updated/dist-upgraded initially.
'post_setup_' - after the *setup* of the chroot is finished.
'post_setup\_' - after the *setup* of the chroot is finished.
Before metadata of the chroot is recorded for later comparison.
'pre_test_' - at the beginning of each test. After metadata of
'pre_test\_' - at the beginning of each test. After metadata of
the chroot was recorded for later comparison.
'is_testable_' - before *installing* your package. If this script
'is_testable\_' - before *installing* your package. If this script
returns a non-zero return value, the installation of the package
will be skipped. With a return value of 1 the test will be reported
as successful, but with a return value if 2 it will be reported as
......@@ -233,59 +264,62 @@ ressources (e.g. some downloader packages) or are broken beyond
repair (e.g. buggy packages in archived releases). Use the return
value of 2 for seriously broken packages that can break piuparts.
'pre_install_' - before *installing* your package. Depending on
'pre_install\_' - before *installing* your package. Depending on
the test, this may be run multiple times. The PIUPARTS_TEST and
PIUPARTS_PHASE variables can be used to distinguish the cases.
'post_install_' - after *installing* your package and its
'post_install\_' - after *installing* your package and its
dependencies. Depending on the test, this may be run multiple
times. The PIUPARTS_TEST and PIUPARTS_PHASE variables can be used
to distinguish the cases.
'pre_remove_' - before *removing* your package.
'pre_remove\_' - before *removing* your package.
Depending on the test, this may be run multiple times.
'post_remove_' - after *removing* your package.
'post_remove\_' - after *removing* your package.
Depending on the test, this may be run multiple times.
'post_purge_' - after *purging* your package.
'post_purge\_' - after *purging* your package.
Depending on the test, this may be run multiple times.
'post_test_' - at the end of each test. Right before performing
'post_test\_' - at the end of each test. Right before performing
final checks and comparing the chroot with the reference chroot
metadata.
'pre_distupgrade_' - before *upgrading* the chroot to the *next
'pre_distupgrade\_' - before *upgrading* the chroot to the *next
distribution*. The next distribution is available in the variable
PIUPARTS_DISTRIBUTION_NEXT.
'post_distupgrade_' - after *upgrading* the chroot to the *next
'post_distupgrade\_' - after *upgrading* the chroot to the *next
distribution*. The previous distribution is available in the
variable PIUPARTS_DISTRIBUTION_PREV.
=== Example custom scripts:
:ref:`top <top1>`
:blue:`Example custom scripts`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: text
'$ cat post_install_numbers'
----
#!/bin/bash
number=`dpkg -l | wc -l`
echo "There are $number packages installed."
exit 0
----
'$ cat post_setup_package'
----
#!/bin/sh
echo "$PIUPARTS_OBJECTS will now get tested."
exit 0
----
== Distributed testing
:ref:`top <top1>`
This is described in README_server.txt.
:blue:`Distributed testing`
^^^^^^^^^^^^^^^^^^^^^^^^^^^
// vim: set filetype=asciidoc:
This is described in README_server.txt.
Notes about the piuparts installation on pejacevic.debian.org and it's slave(s)
===============================================================================
.. raw:: html
<style> .blue {color:navy} </style>
.. role:: blue
.. _top3:
README_perjacevic
=================
:blue:`Notes about the piuparts installation on pejacevic.debian.org and it's slave(s)`
This document describes the setup for https://piuparts.debian.org - it's used
for reference for the Debian System Administrators (DSA) as well as a guide
......@@ -8,7 +22,8 @@ installed from git. For regular installations we recommend to use the
piuparts-master and piuparts-slaves packages as described in
/usr/share/doc/piuparts-master/README_server.txt
== Installation
:blue:`Installation`
^^^^^^^^^^^^^^^^^^^^
piuparts.debian.org is a setup running on three systems:
......@@ -18,7 +33,9 @@ piuparts.debian.org is a setup running on three systems:
actual tests.
* piu-slave-ubc-01.debian.org, running four piuparts-slave nodes as well.
=== piuparts installation from source
:blue:`piuparts installation from source`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* basically, apt-get build-dep piuparts - in reality both systems get their
package configuration from git.debian.org/git/mirror/debian.org.git
......@@ -35,56 +52,71 @@ piuparts.debian.org is a setup running on three systems:
* `sudo ln -s /srv/piuparts.debian.org/etc/piuparts /etc/piuparts`
* See below for further user setup instructions.
=== User setup
:ref:`top <top3>`
:blue:`User setup`
^^^^^^^^^^^^^^^^^^
On pejacevic the piuparts-master user piupartsm needs to be created, on
piu-slave-bm-a and piu-slave-ubc-01 a piupartss user is needed for the slave.
Both are members of the group piuparts and '/srv/piuparts.debian.org' needs to
be chmod 2775 and chown piuparts(sm):piuparts.
==== '~/bashrc' for piupartsm and piupartss
Do this for the piupartsm user on pejacevic and piupartss on the slave(s):
:ref:`top <top3>`
:blue:`'~/bashrc' for piupartsm and piuparts`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Do this for the piupartsm user on pejacevic and piupartss on the slave(s):::
----
piupartsm@pejacevic$ cat >> ~/.bashrc <<-EOF
# added manually for piuparts
umask 0002
export PATH="~/bin:\$PATH"
EOF
----
==== set up ssh pubkey authentification
:ref:`top <top3>`
:blue:`set up ssh pubkey authentification`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Then create an SSH keypair for piupartss and put it into
'/etc/ssh/userkeys/piupartsm' on pejacevic, so the piupartss user can login
with ssh and run only piuparts-master. Restrict it like this:
with ssh and run only piuparts-master. Restrict it like this:::
----
$ cat /etc/ssh/userkeys/piupartsm
command="/srv/piuparts.debian.org/share/piuparts/piuparts-master",from="2001:41c8:1000:21::21:7,5.153.231.7",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-rsa ...
----
=== Setup sudo for the slave(s)
:ref:`top <top3>`
:blue:`Setup sudo for the slave(s)`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is actually done by DSA:
==== '/etc/sudoers' for piu-slave-bm-a and piu-slave-ubc-01
'/etc/sudoers' for piu-slave-bm-a and piu-slave-ubc-01:
.. code-block:: text
----
# The piuparts slave needs to handle chroots.
piupartss ALL = NOPASSWD: /usr/sbin/piuparts *, \
/bin/umount /srv/piuparts.debian.org/tmp/tmp*, \
/usr/bin/test -f /srv/piuparts.debian.org/tmp/tmp*, \
/usr/bin/rm -rf --one-file-system /srv/piuparts.debian.org/tmp/tmp*
----
=== Apache configuration
Any other webserver will do but apache is used on pejacevic (and maintained by DSA):
:ref:`top <top3>`
:blue:`Apache configuration`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Any other webserver will do but apache is used on pejacevic (and maintained by DSA):::
----
<VirtualHost *:80>
ServerName piuparts.debian.org
......@@ -104,39 +136,45 @@ Any other webserver will do but apache is used on pejacevic (and maintained by D
UserDir disabled
</IfModule>
</VirtualHost>
# vim:set syn=apache:
----
== Running piuparts
=== Updating the piuparts installation
:ref:`top <top3>`
:blue:`Running piuparts`
^^^^^^^^^^^^^^^^^^^^^^^^
Updating the master, pejacevic.debian.org:
Updating the piuparts installation
Updating the master, pejacevic.debian.org:::
----
holger@pejacevic~$ sudo su - piupartsm update-piuparts-master-setup develop origin
----
Updating the slave(s), for example on piu-slave-bm-a.debian.org:
----
Updating the slave(s), for example on piu-slave-bm-a.debian.org:::
holger@piu-slave-bm-a~$ sudo su - piupartss update-piuparts-slave-setup develop origin
----
=== Running piuparts
:ref:`top <top3>`
:blue:`Running piuparts`
^^^^^^^^^^^^^^^^^^^^^^^^
When running piuparts in master/slave mode, the master is never run by itself,
instead it is always started by the slave(s).
==== Starting and stopping the slaves
:ref:`top <top3>`
:blue:`Starting and stopping the slaves`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run the following script under *your* user account to start four instances of
piuparts-slave on pejacevic, piuparts-master will be started automatically by
the slaves.
the slaves.::
----
holger@piu-slave-bm-a:~$ sudo -u piupartss -i slave_run
----
There are several cronjobs installed via '~piupartsm/crontab' and
'~piupartss/crontab') to monitor both master and slave as well as the hosts
......@@ -150,22 +188,33 @@ but that may leave temporary directories and processes around.
See the 'piuparts_slave_run (8)' manpage for more information on 'slave_run'.
==== Joining an existing slave session
Run the following script under *your* user account:
:ref:`top <top3>`
:blue:`Joining an existing slave session`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run the following script under *your* user account:::
----
holger@pejacevic:~$ sudo -u piupartss -i slave_join
----
See the 'piuparts_slave_join (8)' manpage for more information on 'slave_join'.
=== Generating reports for the website
:ref:`top <top3>`
:blue:`Generating reports for the website`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
'piuparts-report' is run daily at midnight and at noon from
'~piupartsm/crontab' on pejacevic.
=== Cronjobs to aid problem spotting
:ref:`top <top3>`
:blue:`Cronjobs to aid problem spotting`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some cronjobs to aid problem spotting reside in '~piupartsm/bin/' and are run
daily by '~piupartsm/crontab'.
......@@ -178,10 +227,11 @@ daily by '~piupartsm/crontab'.
More checks should be added as we become aware of them.
== Authors
:ref:`top <top3>`
:blue:`Authors`
^^^^^^^^^^^^^^^
Last updated: February 2017
Holger Levsen <holger@layer-acht.org>
// vim: set filetype=asciidoc:
piuparts README_server
----------------------
.. raw:: html
<style> .blue {color:navy} </style>
.. role:: blue
.. _top:
README_server
-------------
Authors: Lars Wirzenius, Holger Levsen and Andreas Beckmann
Email: <debian-qa@lists.debian.org>
=== piuparts runs itself and other stuff as root
:blue:`piuparts runs itself and other stuff as root`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WARNING: Please note that running piuparts on unknown packages is somewhat
risky, to say the least. There are security implications that you want to
......@@ -14,7 +24,8 @@ access.
You have been warned.
== piuparts in master/slave mode
:blue:`piuparts in master/slave mode`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As part of the quality assurance efforts of Debian, piuparts is
run on the Debian package archive. This requires a lot of
......@@ -28,57 +39,80 @@ of packages it has tested already, and to get more work.
To set this up for yourself, the following steps should suffice:
=== Setting up the master
:blue:`Setting up the master`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
. Pick a machine for running the piuparts master. It cannot be a chroot, but
basically any real (or properly virtualized) Debian system is good enough.
. Install the package 'piuparts-master' on it.
. Create an account for the master, if you install the piuparts-master package
it will automatically create a 'piupartsm' user for you.
. Configure '/etc/piuparts/piuparts.conf' appropriately.
. Create the master and backup directories as defined in that 'piuparts.conf'
and make sure master owns them.
. To generate the web reports, configure your webserver as needed. If you
want to use the supplied 'conf-available/piuparts-master.conf' for apache2,
you will need to do two things: a.) enable it and b.) link the htdocs
directory defined in 'piuparts.conf' to '/var/lib/piuparts/htdocs'
(thats the DocumentRoot as defined in 'conf-available/piuparts-master.conf').
=== Setting up the slave(s)
:ref:`top <top>`
:blue:`Setting up the slave(s)`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
. Pick one or more machines for running one or several piuparts slaves. You
can use the machine which is running the master also for running a slave.
It's also perfectly ok to run several slaves on a multi-core machine which
has lots of IO available.
. Install the package 'piuparts-slave' on it.
. Configure '/etc/piuparts/piuparts.conf' appropriately - if master
and slave share the machine, they also share the config file.
If you want to run more than one slave on a machine, set the slave-count
parameter as desired. By default one slave will be run.
. Create the slave and tmp directories as defined in that 'piuparts.conf' and
make sure the slave can read and write there.
. Create an account for the slave. This must be different from the master
account. The piuparts-slave package will create a 'piupartss' user on
installation. Whether you run one or many slaves, they run with the same
user.
. Create an ssh keypair for the slave. No passphrase. If you installed the
piuparts-slave package this was done automatically and the public key can
be found in '/var/lib/piuparts/piupartss/.ssh/id_rsa.pub'
. Copy the slave's public key to the master's '.ssh/authorized_keys', for
an installation from packages this will be
'/var/lib/piuparts/piupartsm/.ssh/authorized_keys'.
The key should be restricted to only allow running 'piuparts-master'
by prefixing it with
'command="/usr/share/piuparts/piuparts-master",no-port-forwarding,no-X11-forwarding,no-agent-forwarding '
. Configure sudo to allow the slave account to run several commands as root
as root without password. See the example provided in
'/usr/share/doc/piuparts-slave/examples/' to learn which.
. Run '/usr/bin/piuparts_slave_run' and 'piuparts_slave_join' to actually
let the slave(s) run and to join their sessions.
. Run '/usr/bin/piuparts_slave_stop' to stop all piuparts-slaves on a host.
. The logs go into the master account, into subdirectories.
=== Tuning the setup
:ref:`top <top>`
:blue:`Tuning the setup`
^^^^^^^^^^^^^^^^^^^^^^^^
The piuparts-server package installs a piuparts server along the lines of
https://piuparts.debian.org/.
......@@ -98,13 +132,20 @@ There are maintenance cron jobs defined in
piuparts-report will create static html pages, defaulting to
http://localhost/piuparts to be served by any webserver.
=== Setup from GIT
:ref:`top <top>`
:blue:`Setup from GIT`
^^^^^^^^^^^^^^^^^^^^^^
https://piuparts.debian.org has been set up directly from GIT, this is
described in '/usr/share/doc/piuparts-master/README_pejacevic.txt'.
== Distributed piuparts testing protocol
:ref:`top <top>`
:blue:`Distributed piuparts testing protocol`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The slave machine and the piuparts-master program communicate
using a simplistic line based protocol. SSH takes care of
......@@ -128,9 +169,8 @@ the same as for a simple one, the additional lines are prefixed
with a space, and followed by a line containing only a period.
A sample session (">>" indicates what the slave sends, "<<" what
the master responds with):
the master responds with)::
----
<< hello
>> section sid
<< ok
......@@ -142,7 +182,7 @@ the master responds with):
<< ok
>> reserve
<< ok vorbisgain 2.3-4
----
Here the slave first reports a successful test of package liwc,
version 1.2.3-4, and sends the piuparts log file for it. Then it
......@@ -152,38 +192,38 @@ vorbisgain, version 2.3-4.
The communication always starts with the master saying "hello".
The slave shall not speak until the master has spoken.
Commands and responses in this protocol:
Commands and responses in this protocol::
----
Command: section <string>
Success: ok
Failure: error
Failure: busy
----
Slave asks master to select the given section.
This must be the very first command sent by the slave, but may
be repeated later on to switch between sections.
It will return "error" if the section is unknown and "busy" if
it is currently processed by another master instance. If the
section command fails, no other commands than "section" will be
allowed until one succeeds.
allowed until one succeeds.::
----
Command: recycle
Success: ok
Failure: error
----
Slave asks master to enable logfile recycling mode. In this mode
logfiles that have been marked for rechecking will be deleted
and reissued in subsequent "reserve" commands. The "recycle"
command must be issued before the first "reserve" (or "status")
command. It will return "error" if no more logfiles are marked
for rechecking or the command is issued too late.
for rechecking or the command is issued too late.::
----
Command: idle
Success: ok <int>
----
Slave asks master whether it remembers having no packages
available at a previous "reserve" command. Returns 0 (not known
to be idle or timeout expired) or the number of seconds until
......@@ -192,61 +232,57 @@ should be given after "recycle" and logfile submission, but
before "reserve" or "status" commands. If the slave closes the
connection without issuing a "reserve" or "status" command, the
expensive Packages file parsing and status computation will be
skipped.
skipped.::
----
Command: reserve
Success: ok <packagename> <packageversion>
Failure: error
----
Slave asks master to reserve a package (a particular version of
it) for the slave to test. The slave may reserve any number of
packages to test. If the transaction fails, there are no more
packages to test, and the slave should disconnect, wait some time
and try again.
and try again.::
----
Command: unreserve <packagename> <packageversion>
Success: ok
----
Slave informs master it cannot test the desired version of a
package and the package should be rescheduled by the master.
package and the package should be rescheduled by the master.::
----
Command: pass <packagename> <packageversion>
log file contents
.
Success: ok
----
Slave reports that it has tested a particular version of a
package and that the package passed all tests. Master records
this and stores the log file somewhere suitable.
this and stores the log file somewhere suitable.::
----
Command: fail <packagename> <packageversion>
log file contents
.
Success: ok
----
Same as "pass", but package failed one or more tests.
----
Same as "pass", but package failed one or more tests.::
Command: untestable <packagename> <packageversion>
log file contents
.
Success: ok
----
Slave informs master it cannot test the desired version of a
package (perhaps it went away from the mirror?).
package (perhaps it went away from the mirror?).::
----
Command: status
Success: ok <package-state>=<count> <package-state>=<count>...
----
Slave asks master to report the number of packages in all
different states. The "status" command should only be issued
after all logs have been transmitted ("pass", "fail", and
......@@ -261,23 +297,31 @@ The master may likewise abort, without an error message, if the
slave sends garbage, or sends too much data.
== piuparts.conf configuration file
:ref:`top <top>`
:blue:`piuparts.conf configuration file`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
piuparts-master, piuparts-slave and piuparts-report share the
configuration file '/etc/piuparts/piuparts.conf'. The syntax is
defined by the Python ConfigParser class, and is, briefly, like
this:
this:::
----
[master]
foo = bar
----
=== global configuration
:ref:`top <top>`
:blue:`Global Configuration`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These settings have to be placed in the [global] section and are
used for all further sections.
.. code-block:: text
* "sections" defaults to sid and defines which sections should be
processed in master-slave mode. Each section defined here has to
have a section with the section specific settings explained below.
......@@ -343,13 +387,19 @@ used for all further sections.
"http://localhost:3128") due to the high bandwidth consumption of
piuparts and repeated downloading of the same files.
=== section specific configuration
:ref:`top <top>`
:blue:`section specific configuration`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The section specific settings will be reloaded each time a section
is being run. All these keys can be specified in the [global]
section, too, and will serve as defaults for all other sections
(overriding the builtin defaults).
.. code-block:: text
* "master-command" is the command to run on master-host to start
the master. Better then setting it here is actually setting it in
'~piupartsm/.ssh/authorized_keys' to limit ssh access to that
......@@ -376,6 +426,7 @@ section, too, and will serve as defaults for all other sections
* "log-file" is the name of a file to where the master should write
its log messages. In the default configuration file it is
"$SECTION/master.log". To disable logging, set it to "/dev/null".
The global "log-file" setting (defaulting to master-error.log) is
used for logging stderr output from piuparts-master. This logfile
will be placed in the 'master-directory' and has the PID appended.
......@@ -441,7 +492,7 @@ section, too, and will serve as defaults for all other sections
available.
* "arch" is the architecture to use.
Default: dpkg --print-architecture.
Default: dpkg *-*-print-architecture.
* "chroot-tgz" is the name of the file the slave should use for
the tarball containing the base chroot. The default name is
......@@ -486,7 +537,7 @@ section, too, and will serve as defaults for all other sections
seems to work fine. To disable a section set this to 0.
* "keep-sources-list" controls whether the slave runs piuparts
with the '--keep-sources-list' option. This option does not
with the '*-*-keep-sources-list' option. This option does not
apply to upgrade tests. The value should be "yes" or "no", with
the default being "no". Use this option for dists that you need
a custom sources.list for, such as "stable-proposed-updates".
......@@ -576,32 +627,38 @@ section, too, and will serve as defaults for all other sections
should not be used for this section. Useful if a known problem
triggers on (nearly) all logfiles.
Some of the configuration items are not required, but it is best
to set them all to be sure what the configuration actually is.
=== piuparts.debian.org specific configuration
:ref:`top <top>`
:blue:`piuparts.debian.org specific configuration`
In addition to some of the above settings the following
configuration settings are used by the scripts in '~piuparts?/bin/'
used to run piuparts.debian.org. They are all optional, default
values are set in the scripts.
.. code-block:: text
* "urlbase" (global) is the base url of the webserver serving this
piuparts instance. Used to provide links to logfiles in email
reports. It defaults to "https://piuparts.debian.org".
== Running piuparts-report as it is done for piuparts.debian.org
:ref:`top <top>`
:blue:`Running piuparts-report as it is done for piuparts.debian.org`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to run piuparts-report (which is only+very useful if
you run piuparts in master-slave mode), you need to 'apt-get
install python-rpy r-recommended r-base-dev'. For more
information see
link:https://salsa.debian.org/debian/piuparts/blob/develop/README_pejacevic.txt[https://salsa.debian.org/debian/piuparts/blob/develop/README_pejacevic.txt].
"https://salsa.debian.org/debian/piuparts/blob/develop/README_pejacevic.txt".
To generate the report on the master host run:
To generate the report on the master host run:::
----
piupartsm@pejacevic:~$ /usr/share/piuparts/master/generate_daily_report
----
// vim: set filetype=asciidoc:
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'piuparts'
copyright = '2019, Lars Wirzenius'
author = 'Lars Wirzenius'
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = '0.98'
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['ntemplates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.txt'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['nstatic']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'piupartsdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'piuparts.tex', 'piuparts Documentation',
'Lars Wirzenius', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'piuparts', 'piuparts Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'piuparts', 'piuparts Documentation',
author, 'piuparts', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
Welcome to piuparts's documentation!
====================================
.. toctree::
:maxdepth: 4
README
README_server
README_pejacevic
piuparts <piuparts/index.txt>
piuparts slave join <piuparts_slave_join/index.txt>
piuparts slave run <piuparts_slave_run/index.txt>
piuparts slave stop <piuparts_slave_stop/index.txt>
license
Search
======
* :ref:`search`
License GPL-2+
==============
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>
.
On Debian systems, the full text of the GNU General Public
License version 2 can be found in the file
'/usr/share/common-licenses/GPL-2'.
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Piuparts'
copyright = ''
author = ''
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = '0.98'
# source_suffix = ['.rst', '.md']
source_suffix = '.txt'
# The master toctree document.
master_doc = 'index'
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'piupartsdoc'
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'piuparts', '.deb installation, upgrade, and removal testing suite\n',
'', 1)
]
Manpage
=======
.. toctree::
:maxdepth: 1
piuparts.1
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Piuparts'
copyright = ''
author = ''
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = '0.98'
# source_suffix = ['.rst', '.md']
source_suffix = '.txt'
# The master toctree document.
master_doc = 'index'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'piupartsdoc'
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'piuparts_slave_join',
'joins a running piuparts-slave session in screen\n', '', 8)
]
Manpage
=======
.. toctree::
:maxdepth: 1
piuparts slave join <piuparts_slave_join.8>
.. only:: html
piuparts_slave_join(8)
======================
:doctype: manpage
:revdate: 2016-03-06
NAME
----
piuparts_slave_join - join a running piuparts-slave screen session
SYNOPSIS
--------
......@@ -21,13 +21,13 @@ There are no options to this command.
ENVIRONMENT
-----------
Running piuparts in master-slave mode requires configuration in _/etc/piuparts_.
Running piuparts in master-slave mode requires configuration in */etc/piuparts*.
NOTES
-----
Make sure to also read */usr/share/doc/piuparts-master/README_server.txt*.
See *screen*(1) for full instructions on how to navigate between displays. In short:
See *screen* (1) for full instructions on how to navigate between displays. In short::
*Ctrl-A <n>*::
Navigates to display <n>. Slaves are found at screens 1 through 'slave-count', defined in the piuparts configuration file.
......@@ -42,5 +42,3 @@ SEE ALSO
AUTHOR
------
Holger Levsen (holger@layer-acht.org)
// vim: set filetype=asciidoc:
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Piuparts'
copyright = ''
author = ''
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = '0.98'
# source_suffix = ['.rst', '.md']
source_suffix = '.txt'
# The master toctree document.
master_doc = 'index'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'piupartsdoc'
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'piuparts_slave_run', 'start up piuparts-slave instance(s) in screen\n',
'', 8)
]
Manpage
=======
.. toctree::
:maxdepth: 1
piuparts slave run <piuparts_slave_run.8>