sphinx: initial sphinx support

This commit is autogenerated pandoc to generate an inital set
of reST files based on DocBook XML files.

A .rst file is generated for each .xml files in all manuals with this
command:

cd <manual>
for i in *.xml; do \
  pandoc -f docbook -t rst --shift-heading-level-by=-1 \
  $i -o $(basename $i .xml).rst \
done

The conversion was done with: pandoc 2.9.2.1-91 (Arch Linux).

Also created an initial top level index file for each document, and
added all 'books' to the top leve index.rst file.

The YP manuals layout is organized as:

Book
  Chapter
    Section
      Section
        Section

Sphinx uses section headers to create the document structure.
ReStructuredText defines sections headers like that:

   To break longer text up into sections, you use section headers. These
   are a single line of text (one or more words) with adornment: an
   underline alone, or an underline and an overline together, in dashes
   "-----", equals "======", tildes "~~~~~~" or any of the
   non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you feel
   comfortable with. An underline-only adornment is distinct from an
   overline-and-underline adornment using the same character. The
   underline/overline must be at least as long as the title text. Be
   consistent, since all sections marked with the same adornment style
   are deemed to be at the same level:

Let's define the following convention when converting from Docbook:

Book                => overline ===   (Title)
  Chapter           => overline ***   (1.)
    Section         => ====           (1.1)
      Section       => ----           (1.1.1)
        Section     => ~~~~           (1.1.1.1)
          Section   => ^^^^           (1.1.1.1.1)

During the conversion with pandoc, we used --shift-heading-level=-1 to
convert most of DocBook headings automatically. However with this
setting, the Chapter header was removed, so I added it back
manually. Without this setting all headings were off by one, which was
more difficult to manually fix.

At least with this change, we now have the same TOC with Sphinx and
DocBook.

(From yocto-docs rev: 3c73d64a476d4423ee4c6808c685fa94d88d7df8)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 205 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-kickstart.rst b/documentation/ref-manual/ref-kickstart.rst
new file mode 100644
index 0000000000..c019406c6b
--- /dev/null
+++ b/documentation/ref-manual/ref-kickstart.rst
@@ -0,0 +1,205 @@
+*******************************************
+OpenEmbedded Kickstart (``.wks``) Reference
+*******************************************
+
+.. _openembedded-kickstart-wks-reference:
+
+Introduction
+============
+
+The current Wic implementation supports only the basic kickstart
+partitioning commands: ``partition`` (or ``part`` for short) and
+``bootloader``.
+
+.. note::
+
+   Future updates will implement more commands and options. If you use
+   anything that is not specifically supported, results can be
+   unpredictable.
+
+This chapter provides a reference on the available kickstart commands.
+The information lists the commands, their syntax, and meanings.
+Kickstart commands are based on the Fedora kickstart versions but with
+modifications to reflect Wic capabilities. You can see the original
+documentation for those commands at the following link:
+http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html
+
+Command: part or partition
+==========================
+
+Either of these commands creates a partition on the system and uses the
+following syntax: part [mntpoint] partition [mntpoint] If you do not
+provide mntpoint, Wic creates a partition but does not mount it.
+
+The ``mntpoint`` is where the partition is mounted and must be in one of
+the following forms:
+
+-  ``/path``: For example, "/", "/usr", or "/home"
+
+-  ``swap``: The created partition is used as swap space
+
+Specifying a mntpoint causes the partition to automatically be mounted.
+Wic achieves this by adding entries to the filesystem table (fstab)
+during image generation. In order for Wic to generate a valid fstab, you
+must also provide one of the ``--ondrive``, ``--ondisk``, or
+``--use-uuid`` partition options as part of the command.
+
+.. note::
+
+   The mount program must understand the PARTUUID syntax you use with
+   --use-uuid
+   and non-root
+   mountpoint
+   , including swap. The busybox versions of these application are
+   currently excluded.
+
+Here is an example that uses "/" as the mountpoint. The command uses
+``--ondisk`` to force the partition onto the ``sdb`` disk: part /
+--source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
+
+Here is a list that describes other supported options you can use with
+the ``part`` and ``partition`` commands:
+
+-  *``--size``:* The minimum partition size in MBytes. Specify an
+   integer value such as 500. Do not append the number with "MB". You do
+   not need this option if you use ``--source``.
+
+-  *``--fixed-size``:* The exact partition size in MBytes. You cannot
+   specify with ``--size``. An error occurs when assembling the disk
+   image if the partition data is larger than ``--fixed-size``.
+
+-  *``--source``:* This option is a Wic-specific option that names the
+   source of the data that populates the partition. The most common
+   value for this option is "rootfs", but you can use any value that
+   maps to a valid source plugin. For information on the source plugins,
+   see the "`Using the Wic Plugins
+   Interface <&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plugin-interface>`__"
+   section in the Yocto Project Development Tasks Manual.
+
+   If you use ``--source rootfs``, Wic creates a partition as large as
+   needed and fills it with the contents of the root filesystem pointed
+   to by the ``-r`` command-line option or the equivalent rootfs derived
+   from the ``-e`` command-line option. The filesystem type used to
+   create the partition is driven by the value of the ``--fstype``
+   option specified for the partition. See the entry on ``--fstype``
+   that follows for more information.
+
+   If you use ``--source plugin-name``, Wic creates a partition as large
+   as needed and fills it with the contents of the partition that is
+   generated by the specified plugin name using the data pointed to by
+   the ``-r`` command-line option or the equivalent rootfs derived from
+   the ``-e`` command-line option. Exactly what those contents are and
+   filesystem type used are dependent on the given plugin
+   implementation.
+
+   If you do not use the ``--source`` option, the ``wic`` command
+   creates an empty partition. Consequently, you must use the ``--size``
+   option to specify the size of the empty partition.
+
+-  *``--ondisk`` or ``--ondrive``:* Forces the partition to be created
+   on a particular disk.
+
+-  *``--fstype``:* Sets the file system type for the partition. Valid
+   values are:
+
+   -  ``ext4``
+
+   -  ``ext3``
+
+   -  ``ext2``
+
+   -  ``btrfs``
+
+   -  ``squashfs``
+
+   -  ``swap``
+
+-  *``--fsoptions``:* Specifies a free-form string of options to be used
+   when mounting the filesystem. This string is copied into the
+   ``/etc/fstab`` file of the installed system and should be enclosed in
+   quotes. If not specified, the default string is "defaults".
+
+-  *``--label label``:* Specifies the label to give to the filesystem to
+   be made on the partition. If the given label is already in use by
+   another filesystem, a new label is created for the partition.
+
+-  *``--active``:* Marks the partition as active.
+
+-  *``--align (in KBytes)``:* This option is a Wic-specific option that
+   says to start partitions on boundaries given x KBytes.
+
+-  *``--no-table``:* This option is a Wic-specific option. Using the
+   option reserves space for the partition and causes it to become
+   populated. However, the partition is not added to the partition
+   table.
+
+-  *``--exclude-path``:* This option is a Wic-specific option that
+   excludes the given relative path from the resulting image. This
+   option is only effective with the rootfs source plugin.
+
+-  *``--extra-space``:* This option is a Wic-specific option that adds
+   extra space after the space filled by the content of the partition.
+   The final size can exceed the size specified by the ``--size``
+   option. The default value is 10 Mbytes.
+
+-  *``--overhead-factor``:* This option is a Wic-specific option that
+   multiplies the size of the partition by the option's value. You must
+   supply a value greater than or equal to "1". The default value is
+   "1.3".
+
+-  *``--part-name``:* This option is a Wic-specific option that
+   specifies a name for GPT partitions.
+
+-  *``--part-type``:* This option is a Wic-specific option that
+   specifies the partition type globally unique identifier (GUID) for
+   GPT partitions. You can find the list of partition type GUIDs at
+   ` <http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs>`__.
+
+-  *``--use-uuid``:* This option is a Wic-specific option that causes
+   Wic to generate a random GUID for the partition. The generated
+   identifier is used in the bootloader configuration to specify the
+   root partition.
+
+-  *``--uuid``:* This option is a Wic-specific option that specifies the
+   partition UUID.
+
+-  *``--fsuuid``:* This option is a Wic-specific option that specifies
+   the filesystem UUID. You can generate or modify
+   ```WKS_FILE`` <#var-WKS_FILE>`__ with this option if a preconfigured
+   filesystem UUID is added to the kernel command line in the bootloader
+   configuration before you run Wic.
+
+-  *``--system-id``:* This option is a Wic-specific option that
+   specifies the partition system ID, which is a one byte long,
+   hexadecimal parameter with or without the 0x prefix.
+
+-  *``--mkfs-extraopts``:* This option specifies additional options to
+   pass to the ``mkfs`` utility. Some default options for certain
+   filesystems do not take effect. See Wic's help on kickstart (i.e.
+   ``wic help kickstart``).
+
+Command: bootloader
+===================
+
+This command specifies how the bootloader should be configured and
+supports the following options:
+
+.. note::
+
+   Bootloader functionality and boot partitions are implemented by the
+   various
+   --source
+   plugins that implement bootloader functionality. The bootloader
+   command essentially provides a means of modifying bootloader
+   configuration.
+
+-  *``--timeout``:* Specifies the number of seconds before the
+   bootloader times out and boots the default option.
+
+-  *``--append``:* Specifies kernel parameters. These parameters will be
+   added to the syslinux ``APPEND`` or ``grub`` kernel command line.
+
+-  *``--configfile``:* Specifies a user-defined configuration file for
+   the bootloader. You can provide a full pathname for the file or a
+   file that exists in the ``canned-wks`` folder. This option overrides
+   all other bootloader options.