From f3121f0fb75e9cba21a3126a23934909c8d36159 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Wed, 8 Feb 2017 15:45:12 +1100 Subject: [PATCH] Fix up doc errors It seems that pbr's "warnerrors" isn't actually doing anything at the moment (I680b448471e687919d202e8f2abe57f8ba3b22ee) meaning we're able to commit docs with RST parser errors. Fix all these up in some minimal way (I have not audited content, just made it pass build). Link the specs in so they're referenced from the top level. Change-Id: Id67b9ea7ba8f49b43969c58ca3fb7fa1243538a4 --- doc/source/index.rst | 9 ++- doc/source/specs/README.rst | 17 ++-- .../block-device-lvl1-partitioning.rst | 19 +++-- .../v1/approved/block-device-overview.rst | 2 + elements/cloud-init/README.rst | 4 +- elements/debian-minimal/README.rst | 77 ++++++++++--------- elements/partitioning-sfdisk/README.rst | 36 ++++++--- elements/python-brickclient/README.rst | 70 ++++++++++------- elements/rhel7/README.rst | 5 +- 9 files changed, 142 insertions(+), 97 deletions(-) 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` - + * ``__ 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: + ``__) - 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 + ``__ for ``DIB_DISTRIBUTION_MIRROR`` + due to how unreliable it is. Be sure to select a mirror from the + official mirror list at ``__ - 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". + ``__, 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://: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 - To detach: /usr/share/python-brickclient/venv/bin/cinder local-detach +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://:5000/v2.0 local-attach +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://: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 `` + To detach: ``/usr/share/python-brickclient/venv/bin/cinder local-detach `` + +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://:5000/v2.0 local-attach 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.