From 360033027fd51a352b84a62b5613f17c8998e30f Mon Sep 17 00:00:00 2001 From: Gregory Haynes Date: Sun, 29 Mar 2015 16:47:30 +0000 Subject: [PATCH] Create a user guide Our docs are very developer focused. Lets create a separate user guide to help new users get started. Change-Id: I8a03920e6d3306dd0405177875ea55ccb4b40fea --- doc/source/{ => developer}/caches.rst | 0 doc/source/{ => developer}/components.rst | 0 doc/source/{ => developer}/design.rst | 0 .../{ => developer}/developing_elements.rst | 0 doc/source/developer/index.rst | 12 ++++++ doc/source/{ => developer}/install_types.rst | 0 doc/source/{ => developer}/invocation.rst | 0 doc/source/index.rst | 13 ++---- doc/source/user_guide/building_an_image.rst | 42 +++++++++++++++++++ doc/source/user_guide/index.rst | 8 ++++ doc/source/{ => user_guide}/installation.rst | 0 11 files changed, 65 insertions(+), 10 deletions(-) rename doc/source/{ => developer}/caches.rst (100%) rename doc/source/{ => developer}/components.rst (100%) rename doc/source/{ => developer}/design.rst (100%) rename doc/source/{ => developer}/developing_elements.rst (100%) create mode 100644 doc/source/developer/index.rst rename doc/source/{ => developer}/install_types.rst (100%) rename doc/source/{ => developer}/invocation.rst (100%) create mode 100644 doc/source/user_guide/building_an_image.rst create mode 100644 doc/source/user_guide/index.rst rename doc/source/{ => user_guide}/installation.rst (100%) 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 000000000..29f26f321 --- /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 2d04ddf8e..0a02301df 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 000000000..67533bda2 --- /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 000000000..bb1efae14 --- /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