Add a manpage for InstallSystems.

It is in the RST format, so this adds python-docutils as a build-dependency.

Signed-off-by: Sébastien Luttringer <sebastien.luttringer@smartjog.com>

debian/control

@@ -2,7 +2,7 @@ Source: installsystems
 Section: python
 Priority: optional
 Maintainer: Sébastien Luttringer <sebastien.luttringer@smartjog.com>
-Build-Depends: python (>= 2.6), debhelper (>= 7), python-central (>= 0.6), cdbs (>= 0.4.50), python-setuptools
+Build-Depends: python (>= 2.6), debhelper (>= 7), python-central (>= 0.6), cdbs (>= 0.4.50), python-setuptools, python-docutils
 XS-Python-Version: >= 2.6
 Standards-Version: 3.9.1
 

debian/installsystems.manpages

+doc/is.1

doc/is.1.rst

+==
+is
+==
+
+--------------
+InstallSystems
+--------------
+
+:Author: Sébastien Luttringer <sebastien.luttringer@smartjog.com>
+:Manual section: 1
+
+SYNOPSIS
+========
+
+is [options...] command [args...]
+
+SUMMARY
+=======
+
+The InstallSystems is a systems deploy tool. It can easily setup hosts or VMs. This tool gives access to versionned images of systems and configuration scripts. It is a complete solution for mass deployment. It regroups tools for image making, repository management, and easy installing.
+
+You can use InstallSystems with already existent repositories/images or you can make yours using the appropriate is command.
+
+OPTIONS
+=======
+-h, --help
+    show an help message and exit
+
+-V, --version
+    show installsystems version
+
+-v {0,1,2}, --verbosity {0,1,2}
+    show InstallSystems version
+
+-d, --debug
+    enable debug mode
+
+-q, --quiet
+    enable quiet mode
+
+-c *CONFIG*, --config *CONFIG*
+    define path to configuration file
+
+-R *REPO_CONFIG*, --repo-config *REPO_CONFIG*
+    define path to repositories configuration file
+
+-s *REPO*, --repo-search *REPO*
+    search for images inside those repositories
+
+-f *REPO_FILTER*, --repo-filter *REPO_FILTER*
+    filter repositories by name
+
+-r *REPO_PATH*, --repo-path *REPO_PATH*
+    define *REPO_PATH* as a temporary repository
+
+-T *SECONDS*, --repo-timeout *SECONDS*
+    set repositories access timeout to *SECONDS*
+
+--no-cache
+    do not use persistent database caching
+
+--no-sync
+    do not sync repository database cache
+
+--no-color
+    do not display color output
+
+--nice NICE
+    set the *NICE* value for the process
+
+--ionice-class {none,rt,be,idle}
+    ionice class of the process (default: none)
+
+--ionice-level IONICE_LEVEL
+    set the *IONICE_LEVEL* for the process
+
+COMMANDS
+========
+
+Please note that you can display specific help messages for all of
+these commands by using the --help argument after the command name.
+
+add [-h] [-p] *repository* *image*...
+    Add a local *image* to a local *repository*.
+
+    -p, --preserve
+        do not remove *image* after adding it to the *repository*
+
+
+build [-h] [-c] [-C] [-f] [-p] [-s] [*path*]...
+    Check and build the InstallSystems source image in *path* (by default, in the current directory).
+
+    -c, --no-check
+        do not check scripts compilation
+
+    -C, --chdir
+        build image inside source image directory, not in the current one
+
+    -f, --force
+        overwrite existing images
+
+    -p, --payload
+        overwrite existing payloads
+
+    -s, --no-script
+        do not run build scripts
+
+
+cat [-h] path|[repository/]\ *image*\ [:version] *file*...
+    Display one *file* (or more) from *image*. Globbing is allowed for files matching.
+
+
+changelog [-h] [-v]  path|[repository/]\ *image*\ [:version]...
+    Display the last changelog entry for one *image* (or more).
+
+    -v, --all-version
+        display the whole changelog
+
+
+check [-h] *repository*
+    Check a local *repository* for missing, unreferenced and corrupted files.
+
+
+chroot [-h] [-m] [-s *SHELL*\ ] *path*
+    Chroot inside *path*. This is especially usefull to update system images. This mounts filesystems (/proc, /sys, /dev, /dev/pts, /dev/shm), modify a few config files (resolv.conf, mtab) and finally executes a shell in your chroot (default: /bin/bash)
+
+    -m, --no-mount
+        disable mounting of /{proc,dev,sys}
+
+    -s *SHELL*\ , --shell *SHELL*
+        shell to call inside the chroot
+
+
+clean [-h] [-f] *repository*...
+    Clean-up one local *repository* (or more). This will remove files that are no longer referenced in the repository database.
+
+    -f, --force
+        do not prompt before cleaning
+
+
+copy [-h] [-f] *image*... *repository*
+    Copy one *image* (or more) to another local **repository**.
+
+     -f, --force
+         overwrite existing images whithout prompting
+
+
+del [-h] [-f] [-p] *image*...
+    Delete one *image* (or more) from its repository.
+
+    -f, --force
+        delete images whithout prompting
+
+    -p, --preserve
+        do not remove payloads from the repository
+
+
+diff [-h] *object* *object*
+    Show diff between two repositories or images.
+
+
+extract [-h] [-f] [-g] [-p] *image* *path*
+    Extract an InstallSystems *image* into *path*.
+
+    -f, --force
+        overwrite existing destination
+
+    -g, --gen-description
+        generate a description file from metadata
+
+    -p, --payload
+        extract payloads
+
+
+get [-h] [-f] [-I] [-p] *image*...
+Download a remote InstallSystem *image* in current directory.
+
+    -f, --force
+        overwrite existing destination
+
+    -I, --no-image
+        do not get the image (should be combined with -p)
+
+    -p, --payload
+        also get payloads
+
+
+help [-h]
+    Show help.
+
+
+info [-h] [-c] [-j] [-v] *image*...
+    Display info about one *image* (or more).
+
+    -c, --changelog
+        display *image* changelog
+
+    -j, --json
+        output is formated in json
+
+    -v, --verbose
+        verbose output
+
+
+init [-h] *repository*...
+    Create one empty *repository* (or more).
+
+
+install [--dry-run] *image*
+    Install *image*. Each *image* may have specific options. Typically, each one will display a list of available options when using the **--help** argument. In case of trouble during the install you should contact the author of the image. You can find this info in its description file.
+
+    --dry-run
+        do not execute setup scripts
+
+
+list [-h] [-A] [-d] [-D] [-j] [-l] [-m] [-s] [-u] [image...]
+    List available images. By default, it displays the image name and its repository, ordered by repositories/images/version.
+
+    -A, --author
+        display image author
+
+    -d, --date
+        display image date
+
+    -D, --description
+        display image description
+
+    -j, --json
+        output is formated in json
+
+    -l, --long
+        long display
+
+    -m, --md5
+        display image md5
+
+    -s, --size
+        display image size
+
+    -u, --url
+        display image url
+
+
+move [-h] [-f] *image*... *repository*
+    Move one *image* (or more) to another *repository*.
+
+    -f, --force
+        move *image* without confirmation
+
+
+new [-h] [-f] *path*
+    Create a new source image in *path*. It creates the base directories (parser, setup, payload) and a description template. Moreover this command creates samples files for setup, parser and changelog. It also set executable rights on scripts.
+
+    -f, --force
+        overwrite existing source image
+
+
+payload [-h] [-j] [-i] [md5_pattern]...
+    List available payloads matching *md5_pattern* (Default: match everything)
+
+    -j, --json
+        output is formated in json
+
+    -i, --images
+        list images using payload
+
+
+prepare_chroot [-h] [-m] *path*
+    Prepare to chroot in *path*.
+
+    -m, --no-mount
+        disable mounting of /{proc,dev,sys}
+
+
+repo [-h] [-j] [-l|-r] [-o|-O] [-s] [-u] [--purge] [repository]...
+    List available repositories. By defaut, only names are displayed.
+
+    -j, --json
+        output is formated in json
+
+    -l, --local
+        list local repositoriez (filter)
+
+    -r, --remote
+        list remote repositories (filter)
+
+    -o, --online
+        list online repositories (filter)
+
+    -O, --offline
+        list offline repositories (filter)
+
+    -s, --state
+        display repository state (online/offline/local/remote)
+
+    -u, --url
+        display repository url
+
+    --purge
+        remove cache databases
+
+
+search [-h] *pattern*
+    Search *pattern* in repositories.
+
+
+unprepare_chroot [-h] [-m] *path*
+    Remove preparation of a chroot in *path*.
+
+    -m, --no-umount
+        disable unmouting of /{proc,dev,sys}
+
+
+version [-h]
+    Print InstallSystems version.
+
+
+EXAMPLES
+========
+
+Setup a real host and then reboot it.
+
+    is install debian-smartjog -n bobby.seblu.net --disks /dev/sda --reboot
+
+Create of a new image named foobar.
+
+    is new foobar
+
+Build the cdn-fw image
+
+    is build ./images/cdn-fw
+
+IMAGES
+======
+
+InstallSystems use two kind of images:
+
+**source image**
+
+     Each image available in repositories has to be build. The image before building is called a source image. In a source image, there are three directories and two files. Each images make the distinction between scripts and chroot.
+
+    build/
+        Scripts to customize the build process for the image.
+
+    parser/
+        Scripts adding specific options for the image are in this directory.
+
+    setup/
+        The scripts with logical steps of the install are in this directory.
+
+    payload/
+        The payload directory embeds one or more rootfs for the image.
+
+    description
+        It defines the author, the date and the version of the image.
+
+    changelog
+        The changelog file lists modifications of the image.
+
+
+**packaged image**
+
+    Built images are called packaged images. They are versionned, gunzipped and ready to deploy. Like source images, package images still make the difference between scripts and chroot. But it doesn't make difference between parser scripts and setup scripts. In fact you will have at least two tarballs:
+
+    image_name.isimage
+        This tarball contains parser/, setup/, description and changelog.
+
+    image_name.isdata
+        This tarball contains one rootfs from payload/
+
+REPOSITORIES
+============
+
+InstallSystems manages images with repositories.
+
+An InstallSystems repository use a SQLite3 database (db), a last file (last version of images) and Md5s of images. The repos are reachable by HTTP, FTP and SSH. This allows you to easily access images.
+Also, please note that you can only modify local repositories.
+

setup.py

@@ -20,6 +20,10 @@ from setuptools import setup
 import os
 import sys
 import installsystems
+import subprocess
+
+# Build manpage
+subprocess.call(['rst2man', 'doc/is.1.rst', 'doc/is.1'])
 
 # Retrieval of version