Create docs site containing element READMEs

We currently do not have the ability to create a docs site which
outlines all the elements.

Change-Id: I77ccf61e0c4b1509b3e7ce9b8f15ea5ccfd50d9b
This commit is contained in:
Gregory Haynes 2015-02-07 02:30:02 -08:00
parent 1d33465e28
commit c4bbb6f3bc
75 changed files with 494 additions and 13 deletions

View File

@ -267,7 +267,8 @@ Conform to the following conventions:
and not remounted into the filesystem image - if the mount point is needed
again, your element will need to remount it at that point.
### Phase Subdirectories ###
Phase Subdirectories
^^^^^^^^^^^^^^^^^^^^
Make as many of the following subdirectories as you need, depending on what
part of the process you need to customise. The subdirectories are executed in
@ -337,7 +338,8 @@ two-digit numeric prefix, and are executed in numeric order.
* runs: outside chroot
* inputs: $ARCH=i386|amd64|armhf $TARGET\_ROOT=/path/to/target/workarea
### Other Subdirectories ###
Other Subdirectories
^^^^^^^^^^^^^^^^^^^^
Elements may have other subdirectories that are processed by specific elements
rather than the diskimage-builder tools themselves.
@ -346,7 +348,8 @@ One example of this is the ``bin`` directory. The ``rpm-distro``, ``dpkg`` and
``opensuse`` elements install all files found in the ``bin`` directory into
``/usr/local/bin`` within the image as executable files.
### Environment Variables ###
Environment Variables
^^^^^^^^^^^^^^^^^^^^^
To set environment variables for other hooks, add a file to environment.d.
This directory contains bash script snippets that are sourced before running
@ -357,7 +360,8 @@ to the full set of elements that are included in the image build. This can
be used to process local in-element files across all the elements
(pkg-map for example).
### Dependencies ###
Dependencies
^^^^^^^^^^^^
Each element can use the following files to define or affect dependencies:
@ -372,7 +376,8 @@ Each element can use the following files to define or affect dependencies:
### Ramdisk Elements ###
Ramdisk Elements
^^^^^^^^^^^^^^^^
Ramdisk elements support the following files in their element directories:
@ -389,7 +394,8 @@ Ramdisk elements support the following files in their element directories:
* udev.d : udev rules files that will be copied into the ramdisk.
### Element coding standard ###
Element coding standard
^^^^^^^^^^^^^^^^^^^^^^^
- lines should not include trailing whitespace.
- there should be no hard tabs in the file.

View File

@ -0,0 +1,18 @@
# Copyright 2011 OpenStack Foundation
# All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import pbr.version
version_info = pbr.version.VersionInfo('diskimage-builder')

236
doc/source/conf.py Normal file
View File

@ -0,0 +1,236 @@
import sys
import os
# 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 = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'diskimage-builder'
copyright = u'2015, OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
from diskimage_builder import version as dib_version
# The short X.Y version.
release = dib_version.version_info.release_string()
# The full version, including alpha/beta/rc tags.
version = dib_version.version_info.version_string()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build', 'doc/build', '.tox', '.venv']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- 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 = 'default'
# 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 themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# 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 = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'diskimage-builderdoc'
# -- 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': '',
}
# 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 = [
('index', 'diskimage-builder.tex', u'diskimage-builder Documentation',
u'OpenStack', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'diskimage-builder', u'diskimage-builder Documentation',
[u'OpenStack'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- 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 = [
('index', 'diskimage-builder', u'diskimage-builder Documentation',
u'OpenStack', 'diskimage-builder', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

1
doc/source/elements Symbolic link
View File

@ -0,0 +1 @@
../../elements

14
doc/source/index.rst Normal file
View File

@ -0,0 +1,14 @@
.. diskimage-builder documentation master file, created by
sphinx-quickstart on Sat Feb 7 02:01:37 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. include:: ../../README.rst
Elements
========
.. toctree::
:glob:
elements/*/*

View File

@ -1,5 +1,8 @@
Override the default apt.conf
=============================
========
apt-conf
========
This element overrides the default apt.conf.
For APT based systems, if you require specific options for apt operations,
you can define `DIB_APT_CONF` with your favorite apt.conf to override it,

View File

@ -1,4 +1,9 @@
# Create package pins for apt systems if packages need to be held back
===============
apt-preferences
===============
This element creates package pins for apt systems if packages need to be held
back.
For APT based systems, you specify package priorities in the apt preferences file.
This element reads the given manifest file, specified in `DIB_DPKG_MANIFEST`, to

View File

@ -1,4 +1,9 @@
# Override the default sources.list
===========
apt-sources
===========
This element overrides the default sources.list.
For APT based systems, if your network connection is slow for the default
sources.list in the upstream cloud image, you can define `DIB_APT_SOURCES` with

View File

@ -1,3 +1,7 @@
===============================
architecture-emulation-binaries
===============================
This element enables execution for different architectures
When building an image for an architecture that the host machine

View File

@ -1,3 +1,7 @@
=========
baremetal
=========
This is the baremetal (IE: real hardware) element.
Does the following:

View File

@ -1,3 +1,6 @@
====
base
====
This is the base element.
Almost all users will want to include this in their disk image build,

View File

@ -1 +1,4 @@
=========
cache-url
=========
A helper script to download images into a local cache.

View File

@ -1,3 +1,6 @@
==============
centos-minimal
==============
Create a minimal image based on CentOS 7.
Use of this element will also require the tool 'rinse' to be

View File

@ -1,3 +1,6 @@
=======
centos7
=======
Use Centos 7 cloud images as the baseline for built disk images.
For further details see the redhat-common README.

View File

@ -1 +0,0 @@
Remove unused kernel/initrd from the image.

View File

@ -0,0 +1,4 @@
=====================
cleanup-kernel-initrd
=====================
Remove unused kernel/initrd from the image.

View File

@ -1,3 +1,6 @@
======================
cloud-init-datasources
======================
Configures cloud-init to only use an explicit list of data sources.
Cloud-init contains a growing collection of data source modules and most

View File

@ -1,3 +1,6 @@
==================
cloud-init-nocloud
==================
Configures cloud-init to only use on-disk metadata/userdata sources. This
will avoid a boot delay of 2 minutes while polling for cloud data sources
such as the EC2 metadata service.

View File

@ -1,2 +1,5 @@
==============
debian-systemd
==============
You may want to use `systemd` instead of the classic sysv init system.
In this case, include this element in your element list.

View File

@ -1,3 +1,6 @@
==============
debian-upstart
==============
By default Debian will use sysvinit for booting. If you want to experiment
with Upstart, or have need of it due to a need for upstart jobs, this
element will build the image with upstart as the init system.

View File

@ -1,3 +1,6 @@
======
debian
======
Create an image based on Debian. We default to unstable but DIB_RELEASE
is mapped to any series of Debian.

View File

@ -1,2 +1,5 @@
================
deploy-baremetal
================
A ramdisk that will expose the machine primary disk over iSCSI and reboot
once baremetal-deploy-helper signals it is finished.

View File

@ -1,2 +1,5 @@
=============
deploy-ironic
=============
A ramdisk that will expose the machine primary disk over iSCSI and reboot
once Ironic signals it is finished.

View File

@ -1,3 +1,6 @@
============
deploy-kexec
============
Boots into the new image once baremetal-deploy-helper signals
it is finished by downloading the kernel and ramdisk via tftp,
and using the kexec utilities.

View File

@ -1 +1,4 @@
======
deploy
======
Temporary element to include deploy-baremetal from the name deploy whilst renaming the element.

View File

@ -1,3 +1,6 @@
===================
dhcp-all-interfaces
===================
Autodetect network interfaces during boot and configure them for DHCP
The rationale for this is that we are likely to require multiple

View File

@ -1,3 +1,6 @@
====
dkms
====
This is the dkms (Dynamic Kernel Module System) element.
Some distributions such as Fedora and Ubuntu include DKMS in their packaging.

View File

@ -1,3 +1,6 @@
====
dpkg
====
Provide dpkg specific image building glue.
The ubuntu element needs customisations at the start and end of the image build

View File

@ -1 +1,4 @@
==============
dracut-network
==============
Extends dracut and build an initramfs with network support.

View File

@ -1,3 +1,6 @@
==============
dracut-ramdisk
==============
Build Dracut-based ramdisks
This is an alternative to the `ramdisk` element that uses

View File

@ -1,3 +1,4 @@
================
element-manifest
================

View File

@ -1,3 +1,6 @@
=====================
enable-serial-console
=====================
Start getty on active serial consoles.
With ILO and other remote admin environments, having a serial console can be

View File

@ -1,2 +1,5 @@
====
epel
====
This element installs the Extra Packages for Enterprise Linux (EPEL)
repository GPG key as well as configuration for yum.

View File

@ -1,3 +1,6 @@
======
fedora
======
Use Fedora cloud images as the baseline for built disk images.
If you wish to use a Fedora Yum mirror you can set DIB\_DISTRIBUTION\_MIRROR

View File

@ -1,2 +1,5 @@
========
hwburnin
========
A hardware test ramdisk - exercises the machine RAM and exercises the hard
disks

View File

@ -1,3 +1,6 @@
===========
hwdiscovery
===========
A ramdisk to report the hardware of a machine to an inventory service.
This will collect up some basic information about the hardware it

View File

@ -1,3 +1,6 @@
===
ilo
===
Ramdisk support for applying HP iLO firmware.
The firmware files are copied in via an extra-data hook: the variable

View File

@ -1,3 +1,6 @@
==============
install-static
==============
Copy static files into the built image.
The contents of any ``static/`` subdirs of elements will be installed into

View File

@ -1,2 +1,5 @@
============
ironic-agent
============
Build ramdisk with ironic-python-agent.
Works only on Fedora, therefore fedora element is mandatory.

View File

@ -1,3 +1,6 @@
========================
ironic-discoverd-ramdisk
========================
ironic-discoverd [1] is a StackForge project for conducting hardware properties
discovery via booting a special discovery ramdisk and interrogating hardware
from within it.

View File

@ -1,3 +1,6 @@
===
iso
===
Generates a bootable ISO image from the kernel/ramdisk generated by the
elements ``baremetal`` or ``ramdisk``. It uses isolinux to boot on BIOS
machines and grub to boot on EFI machines.

View File

@ -1,2 +1,5 @@
============
local-config
============
Copies local user settings such as .ssh/authorized\_keys and $http\_proxy into
the image.

View File

@ -1,3 +1,6 @@
=========
manifests
=========
Copy any manifests generated into the build area post-image creation
This element should be a dependency of any element that writes a manifest

View File

@ -1 +1,4 @@
========
mellanox
========
Force support for mellanox hardware

View File

@ -1,3 +1,6 @@
==================
modprobe-blacklist
==================
Blacklist specific modules using modprobe.d/blacklist.conf.
In order to use set DIB_MODPROBE_BLACKLIST to the name of your

View File

@ -1,3 +1,6 @@
========
opensuse
========
Use an openSUSE cloud image as the baseline for built disk images. The base
image is located here:

View File

@ -1,3 +1,7 @@
================
package-installs
================
The package-installs element allows for a declarative method of installing and
uninstalling packages for an image build. This is done by creating a
package-installs.yaml or package-installs.json file in the element directory.

View File

@ -1,3 +1,6 @@
=========
pip-cache
=========
# Use a cache for pip
Using a download cache speeds up image builds.

View File

@ -1,3 +1,6 @@
=======
pkg-map
=======
Map package names to distro specific packages.
Provides the following:

View File

@ -1,3 +1,6 @@
====
pypi
====
Inject a PyPI mirror
====================

View File

@ -1 +1,4 @@
============
ramdisk-base
============
Shared functionality required by all of the different ramdisk elements.

View File

@ -1,3 +1,6 @@
=======
ramdisk
=======
This is the ramdisk element.
Almost any user building a ramdisk will want to include this in their build,

View File

@ -1,3 +1,6 @@
==============
rax-nova-agent
==============
Images for Rackspace Cloud currently require nova-agent to get networking
information.

View File

@ -1,3 +1,6 @@
=============
redhat-common
=============
Image installation steps common to RHEL and Fedora.
Overrides:

View File

@ -1,3 +1,6 @@
===========
rhel-common
===========
This element contains the common installation steps between RHEL os releases.
RHEL Registration

View File

@ -1,3 +1,6 @@
====
rhel
====
# Overrides:
## General

View File

@ -1,3 +1,6 @@
=====
rhel7
=====
Use RHEL 7 cloud images as the baseline for built disk images.
Note: As of this writing, RHEL 7 is still in beta, so final download

View File

@ -1,3 +1,6 @@
=========================
select-boot-kernel-initrd
=========================
A helper script to get the kernel and initrd image.
It uses the function select_boot_kernel_initrd from the library img-functions

View File

@ -1,3 +1,6 @@
==================
selinux-permissive
==================
Puts selinux into permissive mode by writing SELINUX=permissive
to /etc/selinux/config

View File

@ -1 +1,4 @@
==============
serial-console
==============
**This element is now deprecated please use enable-serial-console instead**

View File

@ -1,3 +1,6 @@
===================
source-repositories
===================
With this element other elements can register their installation source by
placing their details in the file source-repository-\*. An example
of an element "custom-element" that wants to retrieve the ironic source

View File

@ -1,3 +1,6 @@
======================
stable-interface-names
======================
Does the following:
* Enables stable network interface naming (em1, em2, etc) by

View File

@ -1,3 +1,6 @@
=======
svc-map
=======
Map service names to distro specific services.
Provides the following:

View File

@ -1,3 +1,6 @@
=====
uboot
=====
Perform kernel/initrd post-processing for UBoot.
This element helps post-process the kernel/initrd

View File

@ -1,3 +1,6 @@
===========
ubuntu-core
===========
Use Ubuntu Core cloud images as the baseline for built disk images.
Overrides:

View File

@ -1,3 +1,6 @@
==============
ubuntu-minimal
==============
Create a minimal image based on Ubuntu. We default to trusty but DIB_RELEASE
is mapped to any series of Ubuntu.

View File

@ -1,3 +1,7 @@
======
ubuntu
======
Use Ubuntu cloud images as the baseline for built disk images.
Overrides:

View File

@ -1,3 +1,6 @@
==
vm
==
Sets up a partitioned disk (rather than building just one filesystem with no
partition table).

View File

@ -1,3 +1,6 @@
===
yum
===
Provide yum specific image building glue.
RHEL/Fedora/CentOS and other yum based distributions need specific yum

View File

@ -1,3 +1,6 @@
======
zypper
======
This element provides some customizations for zypper based distributions like
SLES and openSUSE. It works in a very similar way as the yum element does for
yum based distributions.

View File

@ -2,7 +2,7 @@
name = diskimage-builder
summary = Golden Disk Image builder.
description-file =
README.md
README.rst
author = HP Cloud Services
author_email = openstack-dev@lists.openstack.org
license: Apache License (2.0)
@ -14,6 +14,11 @@ classifier =
Programming Language :: Python :: 2.7
Environment :: Console
[build_sphinx]
all_files = 1
build-dir = doc/build
source-dir = doc/source
[files]
packages =
diskimage_builder

View File

@ -6,3 +6,6 @@ hacking>=0.9.2,<0.10
discover
oslotest>=1.2.0 # Apache-2.0
testrepository>=0.0.18
# Doc requirements
sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3

View File

@ -30,4 +30,4 @@ downloadcache = ~/cache/pip
[flake8]
ignore = E125,H202,H302,H803
builtins = _
exclude = .venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build
exclude = .venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build,conf.py