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
This commit is contained in:
Samriddhi Jain 2017-06-17 14:12:37 +05:30
parent f992b1ce42
commit 459f078d0c
35 changed files with 144 additions and 108 deletions

View File

@ -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
authentication. This enables support for additional methods of authentication
that are not provided by the identity store backend and the authentication
plugins that Keystone supports.
<../getting-started/apache-httpd>`, it is possible to have the web server
also handle authentication. This enables support for additional methods of
authentication that are not provided by the identity store backend and
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
-------------

View File

@ -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

View File

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

View File

@ -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
<external-auth>`.
authentication. For more details, refer to :doc:`External Authentication
<advanced-topics/external-auth>`.
Token Drivers and Providers
===========================

View File

@ -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
code at which a successful request calls: router, controller, manager and
As you saw in the :doc:`../getting-started/architecture` document, there are
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`,

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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.environment`.
:doc:`../devref/development_best_practices` and
: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

View File

@ -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
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/
Getting Started
===============
This section sontains the general information related to keystone which is commom to all
the developers, users and operators. For documentation specific to the any of these three,
please see the subsequent sections.
.. toctree::
:maxdepth: 1
:maxdepth: 2
installing
upgrading
performance
apache-httpd
architecture
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
related_projects.rst
getting-started/index.rst
man/index.rst
code_documentation.rst
indices-tables.rst
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/developing_drivers
devref/api_curl_examples
devref/api_change_tutorial
devref/http-api
devref/services
devref/index.rst
Sample Files
============
Operator Documentation
~~~~~~~~~~~~~~~~~~~~~~
This section contains the documentation for operating, deploying and configuring
the keystone service.
.. toctree::
:maxdepth: 1
:maxdepth: 2
sample_config
sample_policy
configuration.rst
advanced-topics/index.rst
sample_files/index.rst
Man Pages
=========
.. toctree::
:maxdepth: 1
man/keystone-manage
Code Documentation
==================
.. toctree::
:maxdepth: 1
api/modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
API Documentation
~~~~~~~~~~~~~~~~~
An end user can find the specific API documentation here, `OpenStack's Identity API`_.

View File

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

7
doc/source/man/index.rst Normal file
View File

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

View File

@ -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/

View File

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

View File

@ -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

View File

@ -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

View File

@ -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'):