diff --git a/doc/source/auth-totp.rst b/doc/source/advanced-topics/auth-totp.rst similarity index 100% rename from doc/source/auth-totp.rst rename to doc/source/advanced-topics/auth-totp.rst diff --git a/doc/source/configure_tokenless_x509.rst b/doc/source/advanced-topics/configure_tokenless_x509.rst similarity index 100% rename from doc/source/configure_tokenless_x509.rst rename to doc/source/advanced-topics/configure_tokenless_x509.rst diff --git a/doc/source/event_notifications.rst b/doc/source/advanced-topics/event_notifications.rst similarity index 100% rename from doc/source/event_notifications.rst rename to doc/source/advanced-topics/event_notifications.rst diff --git a/doc/source/external-auth.rst b/doc/source/advanced-topics/external-auth.rst similarity index 95% rename from doc/source/external-auth.rst rename to doc/source/advanced-topics/external-auth.rst index 0e27a10ca8..24a03fde4d 100644 --- a/doc/source/external-auth.rst +++ b/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 -`, 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 `. +To use this method, Keystone should be running on +:doc:`HTTPD <../getting-started/apache-httpd>`. X.509 example ------------- diff --git a/doc/source/federation/configure_federation.rst b/doc/source/advanced-topics/federation/configure_federation.rst similarity index 100% rename from doc/source/federation/configure_federation.rst rename to doc/source/advanced-topics/federation/configure_federation.rst diff --git a/doc/source/federation/federated_identity.rst b/doc/source/advanced-topics/federation/federated_identity.rst similarity index 100% rename from doc/source/federation/federated_identity.rst rename to doc/source/advanced-topics/federation/federated_identity.rst diff --git a/doc/source/federation/mapping_combinations.rst b/doc/source/advanced-topics/federation/mapping_combinations.rst similarity index 100% rename from doc/source/federation/mapping_combinations.rst rename to doc/source/advanced-topics/federation/mapping_combinations.rst diff --git a/doc/source/federation/mellon.rst b/doc/source/advanced-topics/federation/mellon.rst similarity index 100% rename from doc/source/federation/mellon.rst rename to doc/source/advanced-topics/federation/mellon.rst diff --git a/doc/source/federation/openidc.rst b/doc/source/advanced-topics/federation/openidc.rst similarity index 100% rename from doc/source/federation/openidc.rst rename to doc/source/advanced-topics/federation/openidc.rst diff --git a/doc/source/federation/shibboleth.rst b/doc/source/advanced-topics/federation/shibboleth.rst similarity index 100% rename from doc/source/federation/shibboleth.rst rename to doc/source/advanced-topics/federation/shibboleth.rst diff --git a/doc/source/federation/websso.rst b/doc/source/advanced-topics/federation/websso.rst similarity index 100% rename from doc/source/federation/websso.rst rename to doc/source/advanced-topics/federation/websso.rst diff --git a/doc/source/advanced-topics/index.rst b/doc/source/advanced-topics/index.rst new file mode 100644 index 0000000000..3dc2172fe7 --- /dev/null +++ b/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 diff --git a/doc/source/security_compliance.rst b/doc/source/advanced-topics/security_compliance.rst similarity index 100% rename from doc/source/security_compliance.rst rename to doc/source/advanced-topics/security_compliance.rst diff --git a/doc/source/code_documentation.rst b/doc/source/code_documentation.rst new file mode 100644 index 0000000000..5dbcadbb1a --- /dev/null +++ b/doc/source/code_documentation.rst @@ -0,0 +1,6 @@ +Code Documentation +================== +.. toctree:: + :maxdepth: 1 + + api/modules \ No newline at end of file diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index f10b24dd94..b5e4a2942f 100644 --- a/doc/source/configuration.rst +++ b/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 `. +more details, refer to :doc:`External Authentication +`. 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 +`. Token Drivers and Providers =========================== diff --git a/doc/source/devref/api_change_tutorial.rst b/doc/source/devref/api_change_tutorial.rst index 020c077eb5..967420c208 100644 --- a/doc/source/devref/api_change_tutorial.rst +++ b/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`, diff --git a/doc/source/devref/development_best_practices.rst b/doc/source/devref/development_best_practices.rst index 1b47e1b308..f01674eb50 100644 --- a/doc/source/devref/development_best_practices.rst +++ b/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 diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development_environment.rst similarity index 100% rename from doc/source/devref/development.environment.rst rename to doc/source/devref/development_environment.rst diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst new file mode 100644 index 0000000000..c2778fe4fb --- /dev/null +++ b/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 diff --git a/doc/source/apache-httpd.rst b/doc/source/getting-started/apache-httpd.rst similarity index 98% rename from doc/source/apache-httpd.rst rename to doc/source/getting-started/apache-httpd.rst index 08cb4815bb..23de972547 100644 --- a/doc/source/apache-httpd.rst +++ b/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 diff --git a/doc/source/architecture.rst b/doc/source/getting-started/architecture.rst similarity index 100% rename from doc/source/architecture.rst rename to doc/source/getting-started/architecture.rst diff --git a/doc/source/community.rst b/doc/source/getting-started/community.rst similarity index 100% rename from doc/source/community.rst rename to doc/source/getting-started/community.rst diff --git a/doc/source/getting-started/index.rst b/doc/source/getting-started/index.rst new file mode 100644 index 0000000000..cc35cd5d8a --- /dev/null +++ b/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 diff --git a/doc/source/installing.rst b/doc/source/getting-started/installing.rst similarity index 92% rename from doc/source/installing.rst rename to doc/source/getting-started/installing.rst index 6536e5bb8a..325091b1e3 100644 --- a/doc/source/installing.rst +++ b/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 diff --git a/doc/source/performance.rst b/doc/source/getting-started/performance.rst similarity index 100% rename from doc/source/performance.rst rename to doc/source/getting-started/performance.rst diff --git a/doc/source/policy_mapping.rst b/doc/source/getting-started/policy_mapping.rst similarity index 100% rename from doc/source/policy_mapping.rst rename to doc/source/getting-started/policy_mapping.rst diff --git a/doc/source/upgrading.rst b/doc/source/getting-started/upgrading.rst similarity index 100% rename from doc/source/upgrading.rst rename to doc/source/getting-started/upgrading.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 54e20a2986..c98c333f60 100644 --- a/doc/source/index.rst +++ b/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 -=============== +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`_. diff --git a/doc/source/indices-tables.rst b/doc/source/indices-tables.rst new file mode 100644 index 0000000000..9a9d56c4bb --- /dev/null +++ b/doc/source/indices-tables.rst @@ -0,0 +1,6 @@ +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/doc/source/man/index.rst b/doc/source/man/index.rst new file mode 100644 index 0000000000..cba79b7013 --- /dev/null +++ b/doc/source/man/index.rst @@ -0,0 +1,7 @@ +Man Pages +========= + +.. toctree:: + :maxdepth: 1 + + keystone-manage \ No newline at end of file diff --git a/doc/source/related_projects.rst b/doc/source/related_projects.rst new file mode 100644 index 0000000000..02a62c0828 --- /dev/null +++ b/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/ \ No newline at end of file diff --git a/doc/source/sample_files/index.rst b/doc/source/sample_files/index.rst new file mode 100644 index 0000000000..6294276007 --- /dev/null +++ b/doc/source/sample_files/index.rst @@ -0,0 +1,8 @@ +Sample Files +============ + +.. toctree:: + :maxdepth: 1 + + sample_config + sample_policy \ No newline at end of file diff --git a/doc/source/sample_config.rst b/doc/source/sample_files/sample_config.rst similarity index 71% rename from doc/source/sample_config.rst rename to doc/source/sample_files/sample_config.rst index b170f8483c..fe681dacdc 100644 --- a/doc/source/sample_config.rst +++ b/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 diff --git a/doc/source/sample_policy.rst b/doc/source/sample_files/sample_policy.rst similarity index 79% rename from doc/source/sample_policy.rst rename to doc/source/sample_files/sample_policy.rst index 0b54621674..53e63c72ed 100644 --- a/doc/source/sample_policy.rst +++ b/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 diff --git a/keystone/tests/unit/test_policy.py b/keystone/tests/unit/test_policy.py index e8f649287a..2cf31701c8 100644 --- a/keystone/tests/unit/test_policy.py +++ b/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'):