Convert README.md into rst and include from the docs

README.md

@@ -1,45 +0,0 @@
-bootstrap-vz
-===========================================
-bootstrap-vz is a bootstrapping framework for Debian.
-It is is specifically targeted at bootstrapping systems for virtualized environments.
-bootstrap-vz runs without any user intervention and generates ready-to-boot images for
-[a number of virtualization platforms](http://andsens.github.io/bootstrap-vz/providers.html).
-Its aim is to provide a reproducable bootstrapping process using [manifests](http://andsens.github.io/bootstrap-vz/manifest.html) as well as supporting a high degree of customizability through plugins.
-
-bootstrap-vz was coded from scratch in python once the bash script architecture that was used in the
-[build-debian-cloud](https://github.com/andsens/build-debian-cloud) bootstrapper reached its
-limits.
-
-Documentation
--------------
-The end-user documentation for bootstrap-vz is available
-at [andsens.github.io/bootstrap-vz](http://andsens.github.io/bootstrap-vz).
-There, you can discover [what the dependencies](http://andsens.github.io/bootstrap-vz/#dependencies)
-for a specific cloud provider are, [see a list of available plugins](http://andsens.github.io/bootstrap-vz/plugins.html)
-and learn [how you create a manifest](http://andsens.github.io/bootstrap-vz/manifest.html).
-
-Installation
-------------
-
-bootstrap-vz has a master branch for stable releases and a development for, well, development.  
-After checking out the branch of your choice you can install the python dependencies by running
-`python setup.py install`. However, depending on what kind of image you'd like to bootstrap,
-there are other debian package dependencies as well, at the very least you will need `debootstrap`.  
-[The documentation](http://andsens.github.io/bootstrap-vz/) explains this in more detail.
-
-Note that bootstrap-vz will tell you which tools it requires when they aren't
-present (the different packages are mentioned in the error message), so you can
-simply run bootstrap-vz once to get a list of the packages, install them,
-and then re-run.
-
-Developers
-----------
-The API documentation, development guidelines and an explanation of bootstrap-vz internals
-can be found at [bootstrap-vz.readthedocs.org](http://bootstrap-vz.readthedocs.org).
-
-Contributing
-------------
-
-Contribution guidelines are described on the [CONTRIBUTING](CONTRIBUTING.md) file. There's also a
-[topic on the documentation](http://bootstrap-vz.readthedocs.org/en/development/guidelines.html#coding-style)
-regarding the coding style.

README.rst

@@ -0,0 +1,145 @@
+Introduction
+============
+
+bootstrap-vz is a bootstrapping framework for Debian.
+It is is specifically targeted at bootstrapping systems for virtualized environments.
+bootstrap-vz runs without any user intervention and
+generates ready-to-boot images for a number of virtualization
+platforms.
+Its aim is to provide a reproducable bootstrapping process using
+`manifests <http://andsens.github.io/bootstrap-vz/manifest.html>`__ as
+well as supporting a high degree of customizability through plugins.
+
+bootstrap-vz was coded from scratch in python once the bash script
+architecture that was used in the
+`build-debian-cloud <https://github.com/andsens/build-debian-cloud>`__
+bootstrapper reached its limits.
+
+Documentation
+-------------
+
+The end-user documentation for bootstrap-vz is available at
+`andsens.github.io/bootstrap-vz <http://andsens.github.io/bootstrap-vz>`__.
+There, you can discover `what the
+dependencies <http://andsens.github.io/bootstrap-vz/#dependencies>`__
+for a specific cloud provider are, `see a list of available
+plugins <http://andsens.github.io/bootstrap-vz/plugins.html>`__ and
+learn `how you create a
+manifest <http://andsens.github.io/bootstrap-vz/manifest.html>`__.
+
+Installation
+------------
+
+bootstrap-vz has a master branch for stable releases and a development
+for, well, development.
+
+After checking out the branch of your choice you can install the
+python dependencies by running ``python setup.py install``. However,
+depending on what kind of image you'd like to bootstrap, there are
+other debian package dependencies as well, at the very least you will
+need ``debootstrap``.
+`The documentation <http://andsens.github.io/bootstrap-vz/>`__
+explains this in more detail.
+
+Note that bootstrap-vz will tell you which tools it requires when they
+aren't present (the different packages are mentioned in the error
+message), so you can simply run bootstrap-vz once to get a list of the
+packages, install them, and then re-run.
+
+Quick start
+-----------
+
+Here are a few quickstart tutorials for the most common images.
+If you plan on partitioning your volume, you will need the ``parted``
+package and ``kpartx``:
+
+.. code:: sh
+
+    root@host:~# apt-get install parted kpartx
+
+VirtualBox Vagrant
+~~~~~~~~~~~~~~~~~~
+
+::
+
+    user@host:~$ sudo -i # become root
+    root@host:~# git clone https://github.com/andsens/bootstrap-vz.git # Clone the repo
+    root@host:~# apt-get install qemu-utils debootstrap python-pip # Install dependencies from aptitude
+    root@host:~# pip install termcolor jsonschema fysom docopt pyyaml # Install python dependencies
+    root@host:~# bootstrap-vz/bootstrap-vz bootstrap-vz/manifests/virtualbox-vagrant.manifest.yml
+
+If you want to use the `minimize\_size <dev_Plugins#minimize_size>`__
+plugin, you will have to install the ``zerofree`` package and `VMWare
+Workstation <https://my.vmware.com/web/vmware/info/slug/desktop_end_user_computing/vmware_workstation/10_0>`__
+as well.
+
+Amazon EC2 EBS backed AMI
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: sh
+
+    user@host:~$ sudo -i # become root
+    root@host:~# git clone https://github.com/andsens/bootstrap-vz.git # Clone the repo
+    root@host:~# apt-get install debootstrap python-pip # Install dependencies from aptitude
+    root@host:~# pip install termcolor jsonschema fysom docopt pyyaml boto # Install python dependencies
+    root@host:~# bootstrap-vz/bootstrap-vz bootstrap-vz/manifests/ec2-ebs-debian-official-amd64-pvm.manifest.yml
+
+To bootstrap S3 backed AMIs, bootstrap-vz will also need the
+``euca2ools`` package. However, version 3.2.0 is required meaning you
+must however install it directly from the eucalyptus repository like
+this:
+
+.. code:: sh
+
+    apt-get install --no-install-recommends python-dev libxml2-dev libxslt-dev gcc
+    pip install git+git://github.com/eucalyptus/euca2ools.git@v3.2.0
+
+Cleanup
+-------
+
+bootstrap-vz tries very hard to clean up after itself both if a run was
+successful but also if it failed. This ensures that you are not left
+with volumes still attached to the host which are useless. If an error
+occurred you can simply correct the problem that caused it and rerun
+everything, there will be no leftovers from the previous run (as always
+there are of course rare/unlikely exceptions to that rule). The error
+messages should always give you a strong hint at what is wrong, if that
+is not the case please consider `opening an
+issue <https://github.com/andsens/bootstrap-vz/issues>`__ and attach
+both the error message and your manifest (preferably as a gist or
+similar).
+
+Dependencies
+------------
+
+bootstrap-vz has a number of dependencies depending on the target
+platform and `the selected plugins <dev_Plugins>`__. At a bare minimum
+the following python libraries are needed: \*
+`termcolor <https://pypi.python.org/pypi/termcolor>`__ \*
+`fysom <https://pypi.python.org/pypi/fysom>`__ \*
+`jsonschema <https://pypi.python.org/pypi/jsonschema>`__ \*
+`docopt <https://pypi.python.org/pypi/docopt>`__ \*
+`pyyaml <https://pypi.python.org/pypi/pyyaml>`__ To bootstrap Debian
+itself
+`debootstrap <https://packages.debian.org/wheezy/debootstrap>`__ is
+needed as well.
+
+Any other requirements are dependent upon the manifest configuration
+and are detailed in the corresponding sections of the documentation.
+bootstrap-vz will however warn you if a requirement has not been met,
+before the bootstrapping process begins.
+
+Developers
+----------
+
+The API documentation, development guidelines and an explanation of
+bootstrap-vz internals can be found at
+`bootstrap-vz.readthedocs.org <http://bootstrap-vz.readthedocs.org>`__.
+
+Contributing
+------------
+
+Contribution guidelines are described on the
+`CONTRIBUTING <CONTRIBUTING.md>`__ file. There's also a `topic on the
+documentation <http://bootstrap-vz.readthedocs.org/en/development/guidelines.html#coding-style>`__
+regarding the coding style.

docs/index.rst

@@ -3,14 +3,14 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to bootstrap-vz's documentation!
-========================================
 
-Contents:
+bootstrap-vz
+============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   intro
    manifest
    providers/index
    plugins/index
@@ -21,11 +21,3 @@ Contents:
    howitworks
    switches
    logging
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

docs/intro.rst

@@ -0,0 +1 @@
+.. include:: ../README.rst

docs/providers/index.rst

@@ -1,4 +1,3 @@
-
 Providers
 =========