From bd4d489867024faa0fe772d1c21e9617b38948e4 Mon Sep 17 00:00:00 2001
From: Hongbin Lu <hongbin034@gmail.com>
Date: Sat, 24 Mar 2018 22:36:57 +0000
Subject: [PATCH] Reorganize the documentation index page

This patch reorganize the Zun's documentation home page for
presenting the content better.

Change-Id: I374b0e96ea2f35c68360f68727a757cef4a784ea
---
 doc/source/index.rst                          | 117 +++++++++++++-----
 .../reference/api-microversion-history.rst    |   1 +
 2 files changed, 86 insertions(+), 32 deletions(-)
 create mode 100644 doc/source/reference/api-microversion-history.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 148591b53..c34090ab5 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -14,50 +14,103 @@
 ===============================
 Welcome to Zun's documentation!
 ===============================
-Zun is an OpenStack Container service. It aims to provide an OpenStack API for
-provisioning and managing containerized workload on OpenStack.
 
-Contributor Guide
-~~~~~~~~~~~~~~~~~
+What is Zun?
+=============
+
+Zun is an OpenStack Container service. It aims to provide an API service for
+running application containers without the need to manage servers or clusters.
+
+It requires the following additional OpenStack services for basic function:
+
+* `Keystone <https://docs.openstack.org/keystone/latest/>`__
+* `Neutron <https://docs.openstack.org/neutron/latest/>`__
+* `Kuryr-libnetwork <https://docs.openstack.org/kuryr-libnetwork/latest/>`__
+
+It can also integrate with other services to include:
+
+* `Cinder <https://docs.openstack.org/cinder/latest/>`__
+* `Heat <https://docs.openstack.org/heat/latest/>`__
+* `Glance <https://docs.openstack.org/glance/latest/>`__
+
+For End Users
+=============
+
+As an end user of Zun, you'll use Zun to create and manage containerized
+workload with either tools or the API directly.
+All end user (and some administrative) features of Zun are exposed via a REST
+API, which can be consumed directly. The following resources will help you get
+started with consuming the API directly.
+
+* `API Reference <http://developer.openstack.org/api-ref/application-container/>`_
+
+Alternatively, end users can consume the REST API via various tools or SDKs.
+These tools are collected below.
+
+* `Horizon
+  <https://docs.openstack.org/zun-ui/latest/>`_: The
+  official web UI for the OpenStack Project.
+* `OpenStack Client
+  <https://docs.openstack.org/python-openstackclient/latest/>`_: The official
+  CLI for OpenStack Projects.
+* `Zun Client
+  <https://docs.openstack.org/python-zunclient/latest/>`_: The Python client
+  for consuming the Zun's API.
+
+For Operators
+=============
+
+Installation
+------------
+
+The detailed install guide for Zun. A functioning Zun will also require
+having installed `Keystone
+<https://docs.openstack.org/keystone/latest/install/>`__, `Neutron
+<https://docs.openstack.org/neutron/latest/install/>`__, and `Kuryr-libnetwork
+<https://docs.openstack.org/kuryr-libnetwork/latest/install/>`__.
+Please ensure that you follow their install guides first.
+
+.. toctree::
+   :maxdepth: 2
+
+   install/index
+
+For Contributors
+================
+
+If you are new to Zun, this should help you quickly setup the development
+environment and get started.
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   contributor/quickstart
+
+There are also a number of technical references on various topics.
+These are collected below.
+
 .. toctree::
    :glob:
    :maxdepth: 2
 
    contributor/index
 
-Installation Guide
-~~~~~~~~~~~~~~~~~~
-.. toctree::
-   :maxdepth: 1
-
-   install/index
-
-Command Line Guide
-~~~~~~~~~~~~~~~~~~
+Reference Material
+==================
 
 .. toctree::
-   :maxdepth: 1
+   :glob:
+   :maxdepth: 2
 
    cli/index
-
-Configuration Guide
-~~~~~~~~~~~~~~~~~~~
-
-.. toctree::
-   :maxdepth: 1
-
    configuration/index
-
-Architecture Concepts
-~~~~~~~~~~~~~~~~~~~~~
-
-.. toctree::
-   :maxdepth: 1
-
    user/filter-scheduler
+   reference/api-microversion-history
 
-Indices and tables
-~~~~~~~~~~~~~~~~~~
+Search
+======
 
-* :ref:`genindex`
-* :ref:`search`
+* :ref:`Zun document search <search>`: Search the contents of this document.
+* `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
+  set of OpenStack documentation, including forums.
diff --git a/doc/source/reference/api-microversion-history.rst b/doc/source/reference/api-microversion-history.rst
new file mode 100644
index 000000000..ccc2bbfb2
--- /dev/null
+++ b/doc/source/reference/api-microversion-history.rst
@@ -0,0 +1 @@
+.. include:: ../../../zun/api/rest_api_version_history.rst