Merge "Update docs landing page to follow guideline"

doc/source/index.rst

@@ -15,11 +15,20 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-===========================================
+==============================================
-Cinder, the OpenStack Block Storage Service
+OpenStack Block Storage (Cinder) documentation
-===========================================
+==============================================
 
-Cinder is an OpenStack project to provide "block storage as a service".
+.. figure:: images/cinder.png
+   :alt: Cinder logo
+   :align: center
+
+What is Cinder?
+---------------
+
+Cinder is the OpenStack Block Storage service for providing volumes to Nova
+virtual machines, Ironic bare metal hosts, containers and more. Some of the
+goals of Cinder are to be/have:
 
 * **Component based architecture**: Quickly add new behaviors
 * **Highly available**: Scale to very serious workloads
@@ -27,89 +36,126 @@ Cinder is an OpenStack project to provide "block storage as a service".
 * **Recoverable**: Failures should be easy to diagnose, debug, and rectify
 * **Open Standards**: Be a reference implementation for a community-driven api
 
-This documentation is generated by the Sphinx toolkit and lives in the source
+For end users
-tree. Additional draft and project documentation on Cinder and other components
+-------------
-of OpenStack can be found on the `OpenStack wiki`_. Cloud administrators, refer
-to `docs.openstack.org`_.
 
-.. _`OpenStack wiki`: https://wiki.openstack.org/wiki/Main_Page
+As an end user of Cinder, you'll use Cinder to create and manage volumes using
-.. _`docs.openstack.org`: https://docs.openstack.org
+the Horizon user interface, command line tools such as the
+`python-cinderclient <https://docs.openstack.org/python-cinderclient/latest/>`_,
+or by directly using the
+`REST API <https://developer.openstack.org/api-ref/block-storage/>`_.
 
+Tools for using Cinder
+~~~~~~~~~~~~~~~~~~~~~~
 
-Installation Guide
+* `Horizon <https://docs.openstack.org/horizon/latest/user/manage-volumes.html>`_:
-~~~~~~~~~~~~~~~~~~
+  The official web UI for the OpenStack Project.
+* `OpenStack Client <https://docs.openstack.org/python-openstackclient/latest/>`_:
+  The official CLI for OpenStack Projects. You should use this as your CLI for
+  most things, it includes not just nova commands but also commands for most of
+  the projects in OpenStack.
+* `Cinder Client <https://docs.openstack.org/python-cinderclient/latest/user/shell.html>`_:
+  The **openstack** CLI is recommended, but there are some advanced features
+  and administrative commands that are not yet available there. For CLI access
+  to these commands, the **cinder** CLI can be used instead.
+
+Using the Cinder API
+~~~~~~~~~~~~~~~~~~~~
+
+All features of Cinder are exposed via a REST API that can be used to build
+more complicated logic or automation with Cinder. This can be consumed directly
+or via various SDKs. The following resources can help you get started consuming
+the API directly.
+
+* `Cinder API <https://developer.openstack.org/api-ref/block-storage/>`_
+* :doc:`Cinder microversion history </contributor/api_microversion_history>`
+
+For operators
+-------------
+
+This section has details for deploying and maintaining Cinder services.
+
+Installing Cinder
+~~~~~~~~~~~~~~~~~
+
+Cinder can be configured standalone using the configuration setting
+``auth_strategy = noauth``, but in most cases you will want to at least have
+the `Keystone <https://docs.openstack.org/keystone/latest/install/>`_ Identity
+service and other
+`OpenStack services <https://docs.openstack.org/latest/install/>`_ installed.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    Installation Guide <install/index>
    Upgrade Process <upgrade>
 
-Administration Guide
+Administrating Cinder
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
+
+Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    admin/index
 
-Configuration Reference
+Reference
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~
+
+Contents:
 
 .. toctree::
-    :maxdepth: 2
+   :maxdepth: 1
-
-    configuration/index
-    reference/support-matrix
-    drivers
-
-CLI Reference
-~~~~~~~~~~~~~
-
-Information on the commands available through Cinder's Command Line
-Interface (CLI) can be found in this section of documentation.
-
-Full documentation on the python-cinderclient is in the
-`python-cinderclient documentation`_.
-
-.. _`python-cinderclient documentation`: https://docs.openstack.org/python-cinderclient/latest
-
-.. toctree::
-   :maxdepth: 2
 
+   configuration/index
+   reference/support-matrix
+   drivers
    cli/index
 
-Contributor/Developer Docs
+Additional resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
+
+* `Cinder release notes <https://docs.openstack.org/releasenotes/cinder/>`_
+
+For contributors
+----------------
+
+Contributions to Cinder are welcome. There can be a lot of background
+information needed to get started. This section should help get you started.
+Please feel free to also ask any questions in the **#openstack-cinder** IRC
+channel.
+
+Getting started
+~~~~~~~~~~~~~~~
+
+* `OpenStack Contributor Guide <https://docs.openstack.org/contributors/>`_
+
+Contributing to Cinder
+~~~~~~~~~~~~~~~~~~~~~~
+
+Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    contributor/index
+   API Microversions </contributor/api_microversion_dev/>
 
+Additional reference
+~~~~~~~~~~~~~~~~~~~~
 
-API Extensions
+Contents:
-~~~~~~~~~~~~~~
-
-Go to https://developer.openstack.org/api-ref/block-storage/ for information
-about Cinder API extensions.
-
-:doc:`Block Storage v3 API Microversion History </contributor/api_microversion_history>`:
-The block storage v3 API evolves over time through
-:doc:`API Microversions </contributor/api_microversion_dev/>`. This
-provides the history of all those changes. Consider it a "what's new" in the
-block storage v3 API.
-
-Indices and tables
-~~~~~~~~~~~~~~~~~~
-
-* :ref:`genindex`
-* :ref:`search`
-
-Glossary
-~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
 
    common/glossary.rst
+
+Indices and tables
+~~~~~~~~~~~~~~~~~~
+
+Contents:
+
+* :ref:`genindex`
+* :ref:`search`