diff --git a/doc/source/index.rst b/doc/source/index.rst
index 7d277349c..c683ab654 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -8,7 +8,7 @@ It includes support for building images based on many major
distributions and can produce cloud-images in all common formats
(``qcow2``, ``vhd``, ``raw``, etc), bare metal file-system images and
ram-disk images. These images are composed from the many included
-`elements`; ``diskimage-builder`` acts as a framework to easily add
+``elements``; ``diskimage-builder`` acts as a framework to easily add
your own elements for even further customization.
``diskimage-builder`` is used extensively by the `TripleO project
@@ -35,15 +35,15 @@ Issues
Issues are tracked on launchpad at:
- * `https://bugs.launchpad.net/diskimage-builder/+bugs`
- <https://bugs.launchpad.net/diskimage-builder/+bugs>
+ * `<https://bugs.launchpad.net/diskimage-builder/+bugs>`__
Communication
-------------
Communication among the diskimage-builder developers happens on IRC in
-#openstack-dib on freenode and on the openstack-dev mailing list (openstack-dev@lists.openstack.org).
+``#openstack-dib`` on freenode and on the ``openstack-dev`` mailing list
+(``openstack-dev@lists.openstack.org``).
Table of Contents
@@ -55,3 +55,4 @@ Table of Contents
user_guide/index
developer/index
elements
+ specs/README
diff --git a/doc/source/specs/README.rst b/doc/source/specs/README.rst
index 2840b9b6a..8f9f5e33c 100644
--- a/doc/source/specs/README.rst
+++ b/doc/source/specs/README.rst
@@ -1,10 +1,9 @@
-=======
-README
-=======
-
+================================
diskimage-builder Specifications
================================
+Overview
+========
This directory is used to hold approved design specifications for changes to
the diskimage-builder project. Reviews of the specs are done in gerrit, using a
@@ -46,7 +45,7 @@ given release should only refer to the ``implemented`` directory.
Example specifications
----------------------
-You can find an example spec in ``specs/template.rst``.
+You can find an example spec in :doc:`v1/approved/v1-template`
Backlog specifications
----------------------
@@ -80,3 +79,11 @@ change any of our public APIs are sometimes not required to provide a
specification. The decision of whether something is trivial or not is a
judgement made by the author or by consensus of the project cores, generally
trying to err on the side of spec creation.
+
+Approved Specifications
+=======================
+
+.. toctree::
+ :glob:
+
+ v1/approved/*
diff --git a/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst b/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst
index ec17e9eb7..81b96ffe2 100644
--- a/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst
+++ b/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst
@@ -20,7 +20,9 @@ The implementation for this proposed changed already exists, was
discussed and is currently waiting for reviews [1]. To have a
complete overview over the block device setup, this document is
provided.
+
The dependencies are not implemented as they should be, because
+
* the spec process is currently in the phase of discussion and not
finalized [2],
* the implementation was finished and reviewed before the spec process
@@ -137,14 +139,15 @@ size
Example:
-::
- ["partitioning",
- {"rootdisk": {
- "label": "mbr",
- "partitions":
- [{"name": "part-01",
- "flags": ["boot"],
- "size": "100%"}]}}]
+.. code-block:: yaml
+
+ ["partitioning",
+ {"rootdisk": {
+ "label": "mbr",
+ "partitions":
+ [{"name": "part-01",
+ "flags": ["boot"],
+ "size": "100%"}]}}]
Security impact
---------------
diff --git a/doc/source/specs/v1/approved/block-device-overview.rst b/doc/source/specs/v1/approved/block-device-overview.rst
index 105d413b5..3f10cc8ee 100644
--- a/doc/source/specs/v1/approved/block-device-overview.rst
+++ b/doc/source/specs/v1/approved/block-device-overview.rst
@@ -123,6 +123,7 @@ level or module needs it's own spec.
A first step is to reimplement the existing functionality, this
contains:
+
#. Level 0: Local Loop module
Use loop device on local image file
(This is already implemented: [1])
@@ -133,6 +134,7 @@ contains:
#. Level 3: Mounting
As a second step the following functionality can be added:
+
* Level 1: LVM module
* Level 2: Create File System
(swap)
diff --git a/elements/cloud-init/README.rst b/elements/cloud-init/README.rst
index 707823e48..2f51545af 100644
--- a/elements/cloud-init/README.rst
+++ b/elements/cloud-init/README.rst
@@ -1,6 +1,6 @@
-========
+==========
cloud-init
-========
+==========
Install's and enables cloud-init for systems that don't come with it
pre-installed
diff --git a/elements/debian-minimal/README.rst b/elements/debian-minimal/README.rst
index 66f017218..7a4bd11df 100644
--- a/elements/debian-minimal/README.rst
+++ b/elements/debian-minimal/README.rst
@@ -2,48 +2,51 @@
debian-minimal
==============
-Create a minimal image based on Debian. We default to unstable but `DIB_RELEASE`
-can be set to any series of Debian.
+Create a minimal image based on Debian. We default to unstable but
+``DIB_RELEASE`` can be set to any series of Debian.
There are two ways to configure apt-sources:
1. Using the standard way of defining the default, backports, updates
and security repositories is the default. In this case you can
overwrite the two environment variables to adapt the behavior:
- `DIB_DISTRIBUTION_MIRROR`: the mirror to use
- default: http://ftp.us.debian.org/debian
- `DIB_DEBIAN_COMPONENTS`: (default) `main`
- a comma separated list of components. For Debian this can be
- e.g. `main,contrib,non-free`.
- Note it is not recommended to use http://httpredir.debian.org/ for
- `DIB_DISTRIBUTION_MIRROR` due to how unreliable it is. Be sure to
- select a mirror from the official mirror list:
+ * ``DIB_DISTRIBUTION_MIRROR``: the mirror to use (default:
+ `<http://ftp.us.debian.org/debian>`__)
- https://www.debian.org/mirror/list
+ * ``DIB_DEBIAN_COMPONENTS``: (default: ``main``) a comma
+ separated list of components. For Debian this can be
+ e.g. ``main,contrib,non-free``.
- By default only `main` component is used. If
- `DIB_DEBIAN_COMPONENTS` (comma separated) from the `debootstrap`
- element has been set, that list of components will be used instead.
+ Note it is not recommended to use
+ `<http://httpredir.debian.org/>`__ for ``DIB_DISTRIBUTION_MIRROR``
+ due to how unreliable it is. Be sure to select a mirror from the
+ official mirror list at `<https://www.debian.org/mirror/list>`__
- Backports, updates and security are included unless `DIB_RELEASE`
- is `unstable`.
+ By default only the ``main`` component is used. If
+ ``DIB_DEBIAN_COMPONENTS`` (comma separated) from the
+ ``debootstrap`` element has been set, that list of components will
+ be used instead.
+
+ Backports, updates and security are included unless ``DIB_RELEASE``
+ is ``unstable``.
+
+2. Complete configuration given in the variable ``DIB_APT_SOURCES_CONF``.
-2. Complete configuration given in the variable
- `DIB_APT_SOURCES_CONF`.
Each line contains exactly one entry for the sources.list.d
- directory.
- The first word must be the logical name (which is used as file name
- with `.list` automatically appended), followed by a colon `:`,
- followed by the complete repository specification.
- Example:
- DIB_APT_SOURCES_CONF=\
- "default:deb http://10.0.0.10/ stretch main contrib
- mysecurity:deb http://10.0.0.10/ stretch-security main contrib"
+ directory. The first word must be the logical name (which is used
+ as file name with ``.list`` automatically appended), followed by a
+ colon ``:``, followed by the complete repository specification.
+
+ .. code-block:: bash
+
+ DIB_APT_SOURCES_CONF=\
+ "default:deb http://10.0.0.10/ stretch main contrib
+ mysecurity:deb http://10.0.0.10/ stretch-security main contrib"
If necessary, a custom apt keyring and debootstrap script can be
-supplied to the `debootstrap` command via `DIB_APT_KEYRING` and
-`DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` respectively. Both options require the
+supplied to the ``debootstrap`` command via ``DIB_APT_KEYRING`` and
+``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` respectively. Both options require the
use of absolute rather than relative paths.
Use of this element will also require the tool 'debootstrap' to be
@@ -51,24 +54,24 @@ available on your system. It should be available on Ubuntu, Debian,
and Fedora. It is also recommended that the 'debian-keyring' package
be installed.
-The `DIB_OFFLINE` or more specific `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`
+The ``DIB_OFFLINE`` or more specific ``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE``
variables can be set to prefer the use of a pre-cached root filesystem
tarball.
-The `DIB_DEBOOTSTRAP_EXTRA_ARGS` environment variable may be used to
+The ``DIB_DEBOOTSTRAP_EXTRA_ARGS`` environment variable may be used to
pass extra arguments to the debootstrap command used to create the
-base filesystem image. If --keyring is is used in `DIB_DEBOOTSTRAP_EXTRA_ARGS`,
-it will override `DIB_APT_KEYRING` if that is used as well.
+base filesystem image. If --keyring is is used in ``DIB_DEBOOTSTRAP_EXTRA_ARGS``,
+it will override ``DIB_APT_KEYRING`` if that is used as well.
-For further information about `DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` ,
-`DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` and `DIB_DEBOOTSTRAP_EXTRA_ARGS`
+For further information about ``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` ,
+``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`` and ``DIB_DEBOOTSTRAP_EXTRA_ARGS``
please consult "README.rst" of the debootstrap element.
-------------------
Note on ARM systems
-------------------
-Because there is not a one-to-one mapping of `ARCH` to a kernel package, if
+Because there is not a one-to-one mapping of ``ARCH`` to a kernel package, if
you are building an image for ARM on debian, you need to specify which kernel
-you want in the environment variable `DIB_ARM_KERNEL`. For instance, if you want
-the `linux-image-mx5` package installed, set `DIB_ARM_KERNEL` to `mx5`.
+you want in the environment variable ``DIB_ARM_KERNEL``. For instance, if you want
+the ``linux-image-mx5`` package installed, set ``DIB_ARM_KERNEL`` to ``mx5``.
diff --git a/elements/partitioning-sfdisk/README.rst b/elements/partitioning-sfdisk/README.rst
index 8528e04d1..a3471e32d 100644
--- a/elements/partitioning-sfdisk/README.rst
+++ b/elements/partitioning-sfdisk/README.rst
@@ -5,15 +5,27 @@ Sets up a partitioned disk using sfdisk, according to user needs.
Environment Variables
---------------------
-DIB_PARTITIONING_SFDISK_SCHEMA
- : Required: Yes
- : Default: 2048,,L *
- 0 0;
- 0 0;
- 0 0;
- : Description: A multi-line string specifying a disk schema in sectors.
- : Example: ``DIB_PARTITIONING_SFDISK_SCHEMA="
- 2048,10000,L *
- 10248,,L
- 0 0;
- " will create two partitions on disk, first one will be bootable.
+
+``DIB_PARTITIONING_SFDISK_SCHEMA``
+
+:Required:
+ Yes
+:Default:
+ ::
+
+ 2048,,L *
+ 0 0;
+ 0 0;
+ 0 0;
+:Description:
+ A multi-line string specifying a disk schema in sectors.
+:Example:
+
+ .. code-block:: bash
+
+ DIB_PARTITIONING_SFDISK_SCHEMA="
+ 2048,10000,L *
+ 10248,,L
+ 0 0;"
+
+ will create two partitions on disk, first one will be bootable.
diff --git a/elements/python-brickclient/README.rst b/elements/python-brickclient/README.rst
index 24612815d..aa1850860 100644
--- a/elements/python-brickclient/README.rst
+++ b/elements/python-brickclient/README.rst
@@ -1,34 +1,48 @@
python-brickclient
==================
-* This element is aimed for providing cinder local attach/detach functionality.
+* This element is aimed for providing cinder local attach/detach
+ functionality.
+
* Currently the feature has a dependency on a known bug
- "https://launchpad.net/bugs/1623549", which has been resolved and will be part
- of the upstream with the next release of python-brick-cinderclient-ext.
- Note: Current version of python-brick-cinderclient-ext i.e. 0.2.0 requires and update
- to be made in Line32 fo below script.
- /usr/share/python-brickclient/venv/lib/python2.7/site-packages/brick_cinderclient_ext/__init__.py
- update "brick-python-cinderclient-ext" to "python-brick-cinderclient-ext".
+ `<https://launchpad.net/bugs/1623549>`__, which has been resolved
+ and will be part of the upstream with the next release of
+ ``python-brick-cinderclient-ext``. Note: Current version of
+ ``python-brick-cinderclient-ext`` i.e. 0.2.0 requires and update to
+ be made in Line32 for
+ ``/usr/share/python-brickclient/venv/lib/python2.7/site-packages/brick_cinderclient_ext/__init__.py``:
+ update ``brick-python-cinderclient-ext`` to
+ ``python-brick-cinderclient-ext``.
-* Usage:
- Pass the below shell script to parameter 'user-data' and set 'config-drive=true'
- at the time of provisioning the node via nova-boot to make cinder local
- attach/detach commands talk to your cloud controller.
- [Example of Config Drive Script]
- #!/bin/bash
- FILE="/etc/bash.bashrc"
- [ ! -f "$FILE" ] && touch "$FILE"
- echo 'export OS_AUTH_URL="http://<controller_ip>:5000/v2.0"' >> "$FILE"
- echo 'export OS_PASSWORD="password"' >> "$FILE"
- echo 'export OS_USERNAME="demo"' >> "$FILE"
- echo 'export OS_TENANT_NAME="demo"' >> "$FILE"
- echo 'export OS_PROJECT_NAME="demo"' >> "$FILE"
- exec bash
- To attach: /usr/share/python-brickclient/venv/bin/cinder local-attach <volume_id>
- To detach: /usr/share/python-brickclient/venv/bin/cinder local-detach <volume_id>
+Usage
+-----
-* Alternatively, the same action can be completed manually at the node which does
- not require setting up of config drive such as:
- /usr/share/python-brickclient/venv/bin/cinder --os-username demo --os-password \
- password --os-tenant-name demo --os-project-name demo \
- --os-auth-url=http://<controller_ip>:5000/v2.0 local-attach <volume_id>
+Pass the below shell script to parameter ``user-data`` and set
+``config-drive=true`` at the time of provisioning the node via
+nova-boot to make cinder local attach/detach commands talk to your
+cloud controller.
+
+.. code-block:: bash
+
+ #!/bin/bash
+ FILE="/etc/bash.bashrc"
+ [ ! -f "$FILE" ] && touch "$FILE"
+ echo 'export OS_AUTH_URL="http://<controller_ip>:5000/v2.0"' >> "$FILE"
+ echo 'export OS_PASSWORD="password"' >> "$FILE"
+ echo 'export OS_USERNAME="demo"' >> "$FILE"
+ echo 'export OS_TENANT_NAME="demo"' >> "$FILE"
+ echo 'export OS_PROJECT_NAME="demo"' >> "$FILE"
+ exec bash
+
+ To attach: ``/usr/share/python-brickclient/venv/bin/cinder local-attach <volume_id>``
+ To detach: ``/usr/share/python-brickclient/venv/bin/cinder local-detach <volume_id>``
+
+Alternatively, the same action can be completed manually at the node
+which does not require setting up of config drive such as:
+
+.. code-block:: bash
+
+ /usr/share/python-brickclient/venv/bin/cinder \
+ --os-username demo --os-password password \
+ --os-tenant-name demo --os-project-name demo \
+ --os-auth-url=http://<controller_ip>:5000/v2.0 local-attach <volume_id>
diff --git a/elements/rhel7/README.rst b/elements/rhel7/README.rst
index 11536af01..f387b006e 100644
--- a/elements/rhel7/README.rst
+++ b/elements/rhel7/README.rst
@@ -13,7 +13,10 @@ https://access.redhat.com/downloads/content/69/ver=/rhel---7/7.1/x86_64/product-
Then before running the image build, define DIB_LOCAL_IMAGE (replace the file
name with the one downloaded, if it differs from the example)::
- export DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2
+
+.. code-block:: bash
+
+ export DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2
The downloaded file will then be used as the basis for any subsequent image
builds.