Reorganised keystone documentation structure

Divided the keystone docs into four categories, depending
upon the usage criteria: general information (which will
be common for all), developer documentation,
user documantation and operator documentation.

Change-Id: I2f5dd41acd9874739accc54c4f4fd69460b58334

doc/source/advanced-topics/external-auth.rst

@@ -4,10 +4,10 @@ Using external authentication with Keystone
 .. _external-auth:
 
 When Keystone is executed in a web server like :doc:`Apache HTTPD
-<apache-httpd>`, it is possible to have the web server also handle
+<../getting-started/apache-httpd>`, it is possible to have the web server
-authentication. This enables support for additional methods of authentication
+also handle authentication. This enables support for additional methods of
-that are not provided by the identity store backend and the authentication
+authentication that are not provided by the identity store backend and
-plugins that Keystone supports.
+the authentication plugins that Keystone supports.
 
 Having the web server handle authentication is not exclusive, and both
 Keystone and the web server can provide different methods of authentication at
@@ -72,7 +72,8 @@ server, that will pass down the authenticated user to Keystone using the
 ``REMOTE_USER`` environment variable. This user must exist in advance in the
 identity backend to get a token from the controller.
 
-To use this method, Keystone should be running on :doc:`HTTPD <apache-httpd>`.
+To use this method, Keystone should be running on
+:doc:`HTTPD <../getting-started/apache-httpd>`.
 
 X.509 example
 -------------

doc/source/advanced-topics/index.rst

@@ -0,0 +1,17 @@
+===============
+Advanced Topics
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   federation/federated_identity.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   configure_tokenless_x509.rst
+   auth-totp.rst
+   event_notifications.rst
+   external-auth.rst
+   security_compliance.rst

doc/source/code_documentation.rst

@@ -0,0 +1,6 @@
+Code Documentation
+==================
+.. toctree::
+   :maxdepth: 1
+
+   api/modules

doc/source/configuration.rst

@@ -530,7 +530,8 @@ Keystone provides three authentication methods by default. ``password`` handles
 password authentication and ``token`` handles token authentication.
 ``external`` is used in conjunction with authentication performed by a
 container web server that sets the ``REMOTE_USER`` environment variable. For
-more details, refer to :doc:`External Authentication <external-auth>`.
+more details, refer to :doc:`External Authentication
+<advanced-topics/external-auth>`.
 
 How to Implement an Authentication Plugin
 -----------------------------------------
@@ -578,8 +579,8 @@ The ``REMOTE_USER`` environment variable is only set from a containing
 webserver. However, to ensure that a user must go through other authentication
 mechanisms, even if this variable is set, remove ``external`` from the list of
 plugins specified in ``methods``. This effectively disables external
-authentication. For more details, refer to :doc:`ExternalAuthentication
+authentication. For more details, refer to :doc:`External Authentication
-<external-auth>`.
+<advanced-topics/external-auth>`.
 
 Token Drivers and Providers
 ===========================

doc/source/devref/api_change_tutorial.rst

@@ -22,7 +22,8 @@ Prerequisites
 -------------
 
 In order to follow this tutorial, it is assumed that you have read our
-:doc:`development_best_practices` and :doc:`../architecture` documents.
+:doc:`development_best_practices` and :doc:`../getting-started/architecture`
+documents.
 
 Proposing a change
 ------------------
@@ -73,8 +74,9 @@ code to implement such change.
 Architectural Recapitulation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-As you saw in the :doc:`../architecture` document, there are four logical levels of
+As you saw in the :doc:`../getting-started/architecture` document, there are
-code at which a successful request calls: router, controller, manager and
+four logical levels of code at which a successful request calls: router,
+controller, manager and
 driver.
 
 For the role backend, they can be found in the directory `keystone/assignment`,

doc/source/devref/development_best_practices.rst

@@ -22,7 +22,7 @@ Setting up Keystone
 ===================
 
 Get your development environment set up according to
-:doc:`development.environment`. It is recommended that you install
+:doc:`development_environment`. It is recommended that you install
 Keystone into a virtualenv.
 
 
@@ -235,7 +235,7 @@ Running Tests
 
 Before running tests, you should have ``tox`` installed and available in your
 environment (in addition to the other external dependencies in
-:doc:`development.environment`):
+:doc:`development_environment`):
 
 .. code-block:: bash
 

doc/source/devref/index.rst

@@ -0,0 +1,18 @@
+========================
+Developers Documentation
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   development_best_practices.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   development_environment.rst
+   developing_drivers.rst
+   api_curl_examples.rst
+   api_change_tutorial.rst
+   http-api.rst
+   services.rst

doc/source/getting-started/apache-httpd.rst

@@ -1,4 +1,3 @@
-
 ..
       Copyright 2011-2012 OpenStack Foundation
       All Rights Reserved.
@@ -105,7 +104,7 @@ Update the file to match your system configuration. Note the following:
 
 Keystone's primary configuration file (``etc/keystone.conf``) and the
 PasteDeploy configuration file (``etc/keystone-paste.ini``) must be readable to
-HTTPD in one of the default locations described in :doc:`configuration`.
+HTTPD in one of the default locations described in :doc:`../configuration`.
 
 Configuration file location can be customized using the ``OS_KEYSTONE_CONFIG_DIR``
 environment variable: if this is set, the ``keystone.conf`` file will be searched

doc/source/getting-started/index.rst

@@ -0,0 +1,14 @@
+===============
+Getting Started
+===============
+
+.. toctree::
+    :maxdepth: 1
+
+    installing.rst
+    upgrading.rst
+    performance.rst
+    apache-httpd.rst
+    architecture.rst
+    policy_mapping.rst
+    community.rst

doc/source/getting-started/installing.rst

@@ -21,8 +21,8 @@ Installing Keystone
 
 This document describes how to install Keystone in order to use it. If you are
 intending to develop on or with Keystone, please read
-:doc:`devref/development_best_practices` and
+:doc:`../devref/development_best_practices` and
-:doc:`devref/development.environment`.
+:doc:`../devref/development_environment`.
 
 Installing from Source
 ----------------------
@@ -73,7 +73,7 @@ You will find sample configuration files in ``etc/``:
 * ``policy.json``
 * ``default_catalog.templates``
 
-From here, refer to :doc:`configuration` to choose which backend drivers to
+From here, refer to :doc:`../configuration` to choose which backend drivers to
 enable and use. Once configured, you should be able to run Keystone by issuing
 the command:
 
@@ -83,7 +83,7 @@ the command:
 
 By default, this will show logging on the console from which it was started.
 Once started, you can initialize data in Keystone for use with the rest of
-OpenStack, as described in :doc:`configuration`.
+OpenStack, as described in :doc:`../configuration`.
 
 An excellent reference implementation of setting up Keystone is DEVSTACK_,
 most commonly used for development and testing setup of not only Keystone,
@@ -111,7 +111,7 @@ the Keystone service (`keystone`), and place default configurations in
 all SQL based, stored locally in SQLite.
 
 Once installed, you still need to initialize data in Keystone, which you can
-find described in :doc:`configuration`.
+find described in :doc:`../configuration`.
 
 Installing from packages: Fedora
 --------------------------------
@@ -126,6 +126,6 @@ To install the packages:
     $ sudo yum install openstack-keystone
 
 Once installed, you still need to initialize data in Keystone, which you can
-find described in :doc:`configuration`.
+find described in :doc:`../configuration`.
 
 .. _`OpenStack Install Guide`: https://docs.openstack.org/liberty/install-guide-rdo/keystone-install.html

doc/source/index.rst

@@ -31,104 +31,50 @@ useful.
 .. _`end-user perspective`: https://docs.openstack.org
 
 This documentation is generated by the Sphinx toolkit and lives in the `source
-tree`_. Also see the :doc:`community` page for other ways to interact with the
+tree`_. Also see the :doc:`getting-started/community` page for other ways to interact with the
 community.
 
 .. _`source tree`: https://git.openstack.org/cgit/openstack/keystone/tree/doc/source
 
-Related Identity Projects
+General Information
-=========================
+~~~~~~~~~~~~~~~~~~~
 
-In addition to creating OpenStack's Identity Service, the Keystone team also
+This section sontains the general information related to keystone which is commom to all
-provides a `WSGI middleware`_, an `Authentication library`_ and a `Python
+the developers, users and operators. For documentation specific to the any of these three,
-client library`_.
+please see the subsequent sections.
-
-.. _`WSGI middleware`: https://docs.openstack.org/developer/keystonemiddleware/
-.. _`Authentication library`: https://docs.openstack.org/developer/keystoneauth/
-.. _`Python client library`: https://docs.openstack.org/developer/python-keystoneclient/
-
-Getting Started
-===============
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
-    installing
+    related_projects.rst
-    upgrading
+    getting-started/index.rst
-    performance
+    man/index.rst
-    apache-httpd
+    code_documentation.rst
-    architecture
+    indices-tables.rst
-    policy_mapping
-    community
-
-Configuration
-=============
-
-.. toctree::
-   :maxdepth: 2
-
-   configuration
-
-Advanced Topics
-===============
-
-.. toctree::
-   :maxdepth: 2
-
-   federation/federated_identity
-.. toctree::
-   :maxdepth: 1
-
-   configure_tokenless_x509
-   auth-totp
-   event_notifications
-   external-auth
-   security_compliance
 
 Developers Documentation
-========================
+~~~~~~~~~~~~~~~~~~~~~~~~
-.. toctree::
-   :maxdepth: 2
 
-   devref/development_best_practices
+This section contains the documentation needed for developing keystone.
 
 .. toctree::
-   :maxdepth: 1
+    :maxdepth: 2
 
-   devref/development.environment
+    devref/index.rst
-   devref/developing_drivers
-   devref/api_curl_examples
-   devref/api_change_tutorial
-   devref/http-api
-   devref/services
 
-Sample Files
+Operator Documentation
-============
+~~~~~~~~~~~~~~~~~~~~~~
+
+This section contains the documentation for operating, deploying and configuring
+the keystone service.
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
-    sample_config
+    configuration.rst
-    sample_policy
+    advanced-topics/index.rst
+    sample_files/index.rst
 
-Man Pages
+API Documentation
-=========
+~~~~~~~~~~~~~~~~~
-
+An end user can find the specific API documentation here, `OpenStack's Identity API`_.
-.. toctree::
-    :maxdepth: 1
-
-    man/keystone-manage
-
-Code Documentation
-==================
-.. toctree::
-   :maxdepth: 1
-
-   api/modules
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

doc/source/indices-tables.rst

@@ -0,0 +1,6 @@
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/man/index.rst

@@ -0,0 +1,7 @@
+Man Pages
+=========
+
+.. toctree::
+    :maxdepth: 1
+
+    keystone-manage

doc/source/related_projects.rst

@@ -0,0 +1,10 @@
+Related Identity Projects
+=========================
+
+In addition to creating OpenStack's Identity Service, the Keystone team also
+provides a `WSGI middleware`_, an `Authentication library`_ and a `Python
+client library`_.
+
+.. _`WSGI middleware`: https://docs.openstack.org/developer/keystonemiddleware/
+.. _`Authentication library`: https://docs.openstack.org/developer/keystoneauth/
+.. _`Python client library`: https://docs.openstack.org/developer/python-keystoneclient/

doc/source/sample_files/index.rst

@@ -0,0 +1,8 @@
+Sample Files
+============
+
+.. toctree::
+    :maxdepth: 1
+
+    sample_config
+    sample_policy

doc/source/sample_files/sample_config.rst

@@ -7,6 +7,6 @@ auto-generated from keystone when this documentation is built, so if you are
 having issues with an option, please compare your version of keystone with the
 version of this documentation.
 
-The sample configuration can also be viewed in `file form <_static/keystone.conf.sample>`_.
+The sample configuration can also be viewed in `file form <../_static/keystone.conf.sample>`_.
 
-.. literalinclude:: _static/keystone.conf.sample
+.. literalinclude:: ../_static/keystone.conf.sample

doc/source/sample_files/sample_policy.rst

@@ -10,6 +10,6 @@ to help explain which policy operations protect specific keystone APIs, but it
 is not suggested to copy and paste into a deployment unless you're planning on
 providing a different policy for an operation that is not the default.
 
-The sample policy file can also be viewed in `file form <_static/keystone.policy.yaml.sample>`_.
+The sample policy file can also be viewed in `file form <../_static/keystone.policy.yaml.sample>`_.
 
-.. literalinclude:: _static/keystone.policy.yaml.sample
+.. literalinclude:: ../_static/keystone.policy.yaml.sample

keystone/tests/unit/test_policy.py

@@ -237,7 +237,8 @@ class PolicyJsonTestCase(unit.TestCase):
             # targets.
 
             doc_path = os.path.join(
-                unit.ROOTDIR, 'doc', 'source', 'policy_mapping.rst')
+                unit.ROOTDIR, 'doc', 'source', 'getting-started',
+                'policy_mapping.rst')
             with open(doc_path) as doc_file:
                 for line in doc_file:
                     if line.startswith('Target'):