Browse Source

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
changes/19/475119/6
Samriddhi Jain 5 years ago
parent
commit
459f078d0c
  1. 0
      doc/source/advanced-topics/auth-totp.rst
  2. 0
      doc/source/advanced-topics/configure_tokenless_x509.rst
  3. 0
      doc/source/advanced-topics/event_notifications.rst
  4. 11
      doc/source/advanced-topics/external-auth.rst
  5. 0
      doc/source/advanced-topics/federation/configure_federation.rst
  6. 0
      doc/source/advanced-topics/federation/federated_identity.rst
  7. 0
      doc/source/advanced-topics/federation/mapping_combinations.rst
  8. 0
      doc/source/advanced-topics/federation/mellon.rst
  9. 0
      doc/source/advanced-topics/federation/openidc.rst
  10. 0
      doc/source/advanced-topics/federation/shibboleth.rst
  11. 0
      doc/source/advanced-topics/federation/websso.rst
  12. 17
      doc/source/advanced-topics/index.rst
  13. 0
      doc/source/advanced-topics/security_compliance.rst
  14. 6
      doc/source/code_documentation.rst
  15. 7
      doc/source/configuration.rst
  16. 8
      doc/source/devref/api_change_tutorial.rst
  17. 4
      doc/source/devref/development_best_practices.rst
  18. 0
      doc/source/devref/development_environment.rst
  19. 18
      doc/source/devref/index.rst
  20. 3
      doc/source/getting-started/apache-httpd.rst
  21. 0
      doc/source/getting-started/architecture.rst
  22. 0
      doc/source/getting-started/community.rst
  23. 14
      doc/source/getting-started/index.rst
  24. 12
      doc/source/getting-started/installing.rst
  25. 0
      doc/source/getting-started/performance.rst
  26. 0
      doc/source/getting-started/policy_mapping.rst
  27. 0
      doc/source/getting-started/upgrading.rst
  28. 108
      doc/source/index.rst
  29. 6
      doc/source/indices-tables.rst
  30. 7
      doc/source/man/index.rst
  31. 10
      doc/source/related_projects.rst
  32. 8
      doc/source/sample_files/index.rst
  33. 4
      doc/source/sample_files/sample_config.rst
  34. 4
      doc/source/sample_files/sample_policy.rst
  35. 3
      keystone/tests/unit/test_policy.py

0
doc/source/auth-totp.rst → doc/source/advanced-topics/auth-totp.rst

0
doc/source/configure_tokenless_x509.rst → doc/source/advanced-topics/configure_tokenless_x509.rst

0
doc/source/event_notifications.rst → doc/source/advanced-topics/event_notifications.rst

11
doc/source/external-auth.rst → 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
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
-------------

0
doc/source/federation/configure_federation.rst → doc/source/advanced-topics/federation/configure_federation.rst

0
doc/source/federation/federated_identity.rst → doc/source/advanced-topics/federation/federated_identity.rst

0
doc/source/federation/mapping_combinations.rst → doc/source/advanced-topics/federation/mapping_combinations.rst

0
doc/source/federation/mellon.rst → doc/source/advanced-topics/federation/mellon.rst

0
doc/source/federation/openidc.rst → doc/source/advanced-topics/federation/openidc.rst

0
doc/source/federation/shibboleth.rst → doc/source/advanced-topics/federation/shibboleth.rst

0
doc/source/federation/websso.rst → doc/source/advanced-topics/federation/websso.rst

17
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

0
doc/source/security_compliance.rst → doc/source/advanced-topics/security_compliance.rst

6
doc/source/code_documentation.rst

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

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

8
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
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`,

4
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

0
doc/source/devref/development.environment.rst → doc/source/devref/development_environment.rst

18
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

3
doc/source/apache-httpd.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

0
doc/source/architecture.rst → doc/source/getting-started/architecture.rst

0
doc/source/community.rst → doc/source/getting-started/community.rst

14
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

12
doc/source/installing.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.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

0
doc/source/performance.rst → doc/source/getting-started/performance.rst

0
doc/source/policy_mapping.rst → doc/source/getting-started/policy_mapping.rst

0
doc/source/upgrading.rst → doc/source/getting-started/upgrading.rst

108
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
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
===============
.. toctree::
:maxdepth: 1
installing
upgrading
performance
apache-httpd
architecture
policy_mapping
community
Configuration
=============
.. toctree::
:maxdepth: 2
configuration
Advanced Topics
===============
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: 2
: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
.. toctree::
:maxdepth: 1
devref/development.environment
devref/developing_drivers
devref/api_curl_examples
devref/api_change_tutorial
devref/http-api
devref/services
~~~~~~~~~~~~~~~~~~~~~~~~
Sample Files
============
This section contains the documentation needed for developing keystone.
.. toctree::
:maxdepth: 1
:maxdepth: 2
sample_config
sample_policy
devref/index.rst
Man Pages
=========
Operator Documentation
~~~~~~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
This section contains the documentation for operating, deploying and configuring
the keystone service.
man/keystone-manage
Code Documentation
==================
.. toctree::
:maxdepth: 1
api/modules
:maxdepth: 2
Indices and tables
==================
configuration.rst
advanced-topics/index.rst
sample_files/index.rst
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
API Documentation
~~~~~~~~~~~~~~~~~
An end user can find the specific API documentation here, `OpenStack's Identity API`_.

6
doc/source/indices-tables.rst

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

7
doc/source/man/index.rst

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

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

8
doc/source/sample_files/index.rst

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

4
doc/source/sample_config.rst → 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

4
doc/source/sample_policy.rst → 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

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

Loading…
Cancel
Save