Reformat README as ReST and include in built docs

I've renamed the README and tweaked its formatting to be valid
ReStructured Text rather than markdown.

This allows it to be included in the built docs; which means our other
docs can link directly to a section of the README (rather than just
telling users to "go find the README somewhere and look for a
heading").

The major changes are slightly different formatting for the headings
and subheadings and sub-sub-headings, and using explicit enumeration
for the lists.

ReST can handle auto-enumeration, or monotonically increasing explicit
enumeration, but when it sees the "1." marker again it assumes a new
list is being started, which gets it confused. I've opted for explicit
enumeration as it ensures the reader gets the same understanding
whether looking at the source or the generated document.

I've tweaked a few of the links to point at the local doc rather than
the docs.o.o version, to improve consistency for someone reading docs
from a particular checkout. I have assumed that anyone who needs to
read the d.o.o versions knows how to find them.

Change-Id: I964fd5228b4f1fb863fb3fd138ba862cad9303e6

README.rst

@@ -1,5 +1,5 @@
 OpenStack on OpenStack, or TripleO
-===================================
+==================================
 
 Welcome to our TripleO incubator! TripleO is our pithy term for OpenStack
 deployed on and with OpenStack. This repository is our staging area, where we
@@ -75,7 +75,8 @@ a full HA story in place, which leads to requiring a long lived seed facility
 rather than a fully self-sustaining infrastructure.  We track bugs affecting
 TripleO itself at https://bugs.launchpad.net/tripleo/.
 
-### Diskimage-builder
+Diskimage-builder
+^^^^^^^^^^^^^^^^^
 
 The lowest layer in the dependency stack, diskimage-builder, can be used to
 customise generic disk images for use with Nova bare metal. It can also be
@@ -83,7 +84,8 @@ used to provide build-time specialisation for disk images. Diskimage-builder
 is quite mature and can be downloaded from
 https://git.openstack.org/cgit/openstack/diskimage-builder.
 
-### Nova bare-metal / Ironic
+Nova bare-metal / Ironic
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 The next layer up, In OpenStack Grizzly Nova bare-metal is able to deliver
 ephemeral instances to physical machines with multiple architectures.
@@ -120,7 +122,8 @@ Caveats / limitations:
  - Node deployment to large numbers of nodes can saturate networks - content is
    deployed using dd + iscsi (rather than e.g. bittorrent).
 
-### Heat
+Heat
+^^^^
 
 Heat is the orchestration layer in TripleO - it glues the various services
 together in the cluster, arbitrates deployments and reconfiguration.
@@ -139,7 +142,8 @@ Caveats / limitations:
    rather than also coordinating with monitoring systems. Workaround by 
    tying your monitoring back into Heat to trigger rollbacks.
 
-### os-apply-config/os-refresh-config/os-collect-config
+os-apply-config/os-refresh-config/os-collect-config
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 These tools work with the Heat delivered metadata to create configuration
 files on disk (os-apply-config), and to trigger in-instance reconfiguration
@@ -158,7 +162,8 @@ os-collect-config subscribes to the Heat metadata we're using, and then invokes
 hooks - it can be used to drive os-refresh-config, or Chef/Puppet/Salt or other
 configuration management tools.
 
-### tripleo-image-elements
+tripleo-image-elements
+^^^^^^^^^^^^^^^^^^^^^^
 
 These diskimage-builder elements create build-time specialised disk/partition
 images for TripleO. The elements build images with software installed but
@@ -176,7 +181,8 @@ Caveats/Limitations:
    sense such as running a very minimal number of nodes but still wanting HA).
    This is primarily (but not entirely) configuration.
 
-### tripleo-heat-templates
+tripleo-heat-templates
+^^^^^^^^^^^^^^^^^^^^^^
 
 These templates provide the rules describing how to deploy the baremetal
 undercloud and virtual overclouds. This also includes a python module used
@@ -191,23 +197,22 @@ Additionally as by definition it will replace existing facilities (be those
 manual or automated) within an organisation, some care is needed to make
 migration, or integration smooth.
 
-This is a sufficiently complex topic, we've created a dedicated document for
+This is a sufficiently complex topic, we've created a dedicated document for it
-it - [Deploying TripleO] (http://docs.openstack.org/developer/tripleo-incubator/deploying.html).
+- :doc:`deploying`.  A related document is the instructions for doing
-A related document is the
+:doc:`dev/test of TripleO <devtest>`.
-instructions for doing [Dev/Test of TripleO] (http://docs.openstack.org/developer/tripleo-incubator/devtest.html)
 
 Architecture
 ------------
 
-There is a [high level presentation] (presentations/TripleO architecture overview.odp)
+There is a :download:`high level presentation <../../presentations/TripleO
-accompanying these docs.
+architecture overview.odp>` accompanying these docs.
 
-We start with an [image builder]
+We start with an `image builder
-(https://git.openstack.org/cgit/openstack/diskimage-builder/), and rules for that to
+<https://git.openstack.org/cgit/openstack/diskimage-builder/>`_, and rules for that to
-[build OpenStack images] (https://git.openstack.org/cgit/openstack/tripleo-image-elements/).
+`build OpenStack images <https://git.openstack.org/cgit/openstack/tripleo-image-elements/>`_.
-We then use [Heat] (https://git.openstack.org/cgit/openstack/heat) to orchestrate deployment
+We then use `Heat <https://git.openstack.org/cgit/openstack/heat>`_ to orchestrate deployment
-of those images onto bare metal using the [Nova baremetal driver]
+of those images onto bare metal using the `Nova baremetal driver
-(https://wiki.openstack.org/wiki/Baremetal).
+<https://wiki.openstack.org/wiki/Baremetal>`_.
 
 Eventually we will have the Heat instance we use to deploy both the undercloud
 and overcloud hosted in the undercloud. That depends on a full-HA setup so that
@@ -225,9 +230,9 @@ So this gives us three clouds:
 
 1. A KVM hosted single-node bare-metal cloud that owns a small set of machines
    we deploy the undercloud onto. This is the 'seed cloud'.
-1. A baremetal hosted single-node bare-metal cloud that owns the rest of the
+2. A baremetal hosted single-node bare-metal cloud that owns the rest of the
    datacentre and we deploy the overcloud onto. The is the 'under cloud'.
-1. A baremetal hosted many-node KVM cloud which is deployed on the undercloud.
+3. A baremetal hosted many-node KVM cloud which is deployed on the undercloud.
    This is the user facing cloud - the 'over cloud'.
 
 Within each machine we use small focused tools for converting Heat metadata to
@@ -250,9 +255,9 @@ OpenStack on OpenStack with three distinct clouds:
 1. A seed cloud, runs baremetal nova-compute and deploys instances on bare
    metal. Hosted in a KVM or similar virtual machine within a manually
    installed machine. This is used to deploy the under cloud.
-1. The under cloud, runs baremetal nova-compute and deploys instances on bare
+2. The under cloud, runs baremetal nova-compute and deploys instances on bare
    metal, is managed and used by the cloud sysadmins.
-1. The over cloud, which runs using the same images as the under cloud, but as
+3. The over cloud, which runs using the same images as the under cloud, but as
    a tenant on the undercloud, and delivers virtualised compute machines rather
    than bare metal machines.
 
@@ -285,9 +290,9 @@ Stage N
 OpenStack on itself: OpenStack on OpenStack with one cloud:
 
 1. The under cloud is used ts in Stage 1.
-1. KVM or Xen Nova compute nodes are deployed into the cloud as part of the
+2. KVM or Xen Nova compute nodes are deployed into the cloud as part of the
    admin tenant, and offer their compute capacity to the under cloud.
-1. Low overhead services can be redeployed as virtual machines rather than
+3. Low overhead services can be redeployed as virtual machines rather than
    physical (as long as they are machines which the cluster can be rebooted
    without.
 
@@ -310,18 +315,18 @@ Principles
 1. Developer tools (like disk-image-builder) should have a non-intrusive
    footprint on the machine of users. Requiring changing of global settings
    is poor form.
-1. Where possible we run upstream code and settings without modification - e.g.
+2. Where possible we run upstream code and settings without modification - e.g.
    we strongly prefer to use upstream defaults rather than our own. Only if
    there is no right setting in production should we change things.
-1. We only prototype tools in tripleo-incubator: when they are ready for
+3. We only prototype tools in tripleo-incubator: when they are ready for
    production use with stable APIs, we move them to some appropriate
    repository.
-1. We include everyone who wants to deploy OpenStack using OpenStack tooling
+4. We include everyone who wants to deploy OpenStack using OpenStack tooling
    in the TripleO community - we support folk that want to use packages
    rather than source, or Xen rather than KVM, or Puppet / chef / salt etc.
-1. Simple is hard to achieve but very valuable - and we value it. Things
+5. Simple is hard to achieve but very valuable - and we value it. Things
    that complect or confound concepts may need more design work to work well.
-1. We use OpenStack projects in preference to any others (even possibly to the
+6. We use OpenStack projects in preference to any others (even possibly to the
    exclusion of alternative backends). For instance, we have a hard dependency
    on Heat, rather than alternative cluster definition tools. This says nothing
    about the quality of such tools, rather that we want a virtuous circle where
@@ -343,9 +348,9 @@ your nodes directly with the seed - the seed and the undercloud are
 functionally identical and can both deploy an overcloud.
 
 When building lots of images, be sure to pass -u and --offline into
-diskimage-builder. One way to do this is via DIB\_COMMON\_ELEMENTS though this
+diskimage-builder. One way to do this is via ``DIB_COMMON_ELEMENTS`` though this
-doesn't affect the demo 'user' image we build at the end of
+doesn't affect the demo `user` image we build at the end of
-``devtest_overcloud.sh``. To affect that, export NODE\_DIST - which will affect
+``devtest_overcloud.sh``. To affect that, export ``NODE_DIST`` - which will affect
 all images. e.g. ``ubuntu --offline -u``. --offline prevents all cache
 freshness checks and ensures the elements like ``pypi`` which use some online
 resources disable those resources (if possible).

doc/source/README.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst

doc/source/index.rst

@@ -4,6 +4,7 @@ TripleO Incubator
 .. toctree::
    :maxdepth: 1
 
+   README
    userguide
 
    devtest

scripts/devtest.sh

@@ -114,6 +114,9 @@ fi
 ##    notes (such as those relating to setting up local mirrors for apt and
 ##    pypi) will probably be helpful for everyone.
 
+## More details about the TripleO project and its goals can be found in the
+## :doc:`README <README>`
+
 ## Permissions
 ## -----------
 

setup.cfg

@@ -4,7 +4,7 @@ author = OpenStack
 author-email = openstack-dev@lists.openstack.org
 summary = Incubator for TripleO
 description-file = 
-	README.md
+	README.rst
 home-page = http://git.openstack.org/cgit/openstack/tripleo-incubator
 classifier = 
 	Environment :: OpenStack