diff --git a/doc/source/caches.rst b/doc/source/developer/caches.rst similarity index 100% rename from doc/source/caches.rst rename to doc/source/developer/caches.rst diff --git a/doc/source/components.rst b/doc/source/developer/components.rst similarity index 100% rename from doc/source/components.rst rename to doc/source/developer/components.rst diff --git a/doc/source/design.rst b/doc/source/developer/design.rst similarity index 100% rename from doc/source/design.rst rename to doc/source/developer/design.rst diff --git a/doc/source/developing_elements.rst b/doc/source/developer/developing_elements.rst similarity index 100% rename from doc/source/developing_elements.rst rename to doc/source/developer/developing_elements.rst diff --git a/doc/source/developer/index.rst b/doc/source/developer/index.rst new file mode 100644 index 00000000..29f26f32 --- /dev/null +++ b/doc/source/developer/index.rst @@ -0,0 +1,12 @@ +Developer Documentation +======================= + +.. toctree:: + :maxdepth: 2 + + design + components + invocation + caches + install_types + developing_elements diff --git a/doc/source/install_types.rst b/doc/source/developer/install_types.rst similarity index 100% rename from doc/source/install_types.rst rename to doc/source/developer/install_types.rst diff --git a/doc/source/invocation.rst b/doc/source/developer/invocation.rst similarity index 100% rename from doc/source/invocation.rst rename to doc/source/developer/invocation.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 2d04ddf8..0a02301d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,14 +13,7 @@ easier. .. toctree:: :maxdepth: 2 - - design - components - installation - invocation - caches - install_types - developing_elements - elements - copyright + user_guide/index + developer/index + elements diff --git a/doc/source/user_guide/building_an_image.rst b/doc/source/user_guide/building_an_image.rst new file mode 100644 index 00000000..67533bda --- /dev/null +++ b/doc/source/user_guide/building_an_image.rst @@ -0,0 +1,42 @@ +Building An Image +================= + +Now that you have diskimage-builder properly :doc:`installed ` +you can get started by building your first disk image. + +VM Image +-------- + +Our first image is going to be a bootable vm image using one of the standard +supported distribution :doc:`elements <../elements>` (Ubuntu or Fedora). + +The following command will start our image build (distro must be either +'ubuntu' or 'fedora'): + +:: + + disk-image-create vm + +This will create a qcow2 file 'image.qcow2' which can then be booted. + +Elements +-------- + +It is important to note that we are passing in a list of +:doc:`elements <../elements>` to disk-image-create in our above command. Elements +are how we decide what goes into our image and what modifications will be +performed. + +Some elements provide a root filesystem, such as the ubuntu or fedora element +in our example above, which other elements modify to create our image. At least +one of these 'distro elements' must be specified when performing an image +build. It's worth pointing out that there are many distro elements (you can even +create your own), and even multiples for some of the distros. This is because +there are often multiple ways to install a distro which are very different. +For example: One distro element might use a cloud image while another uses +a package installation tool to build a root filesystem for the same distro. + +Other elements modify our image in some way. The 'vm' element in our example +above ensures that our image has a bootloader properly installed. This is only +needed for certain use cases and certain output formats and therefore it is +not performed by default. diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst new file mode 100644 index 00000000..bb1efae1 --- /dev/null +++ b/doc/source/user_guide/index.rst @@ -0,0 +1,8 @@ +User Guide +========== + +.. toctree:: + :maxdepth: 1 + + installation + building_an_image diff --git a/doc/source/installation.rst b/doc/source/user_guide/installation.rst similarity index 100% rename from doc/source/installation.rst rename to doc/source/user_guide/installation.rst