openstack/keystone
Code Issues Proposed changes

Merge "Added new subsections to developer docs"

Browse Source
This commit is contained in:
Jenkins 2017-07-26 17:58:19 +00:00 committed by Gerrit Code Review
commit 995e013e16
10 changed files with 130 additions and 205 deletions

19
doc/source/devref/build-docs.rst → doc/source/devref/architecture.rst

@ -14,16 +14,13 @@
License for the specific language governing permissions and limitations
under the License.
==========================
Building the Documentation
==========================
===============================
Learning Architecture Internals
===============================
The documentation is generated with Sphinx using the tox command. To create HTML
docs and man pages:
.. toctree::
:maxdepth: 1
.. code-block:: bash
$ tox -e docs
The results are in the ``doc/build/html`` and ``doc/build/man`` directories
respectively.
caching-layer.rst
filtering-responsibilities.rst
list-truncation.rst

40
doc/source/devref/conf.rst

@ -1,40 +0,0 @@
..
Copyright 2011-2012 OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Configuring Keystone with a sample file
=======================================
Keystone requires a configuration file. Keystone's sample configuration file
``etc/keystone.conf.sample`` is automatically generated based upon all of the
options available within Keystone. These options are sourced from the many
files around Keystone as well as some external libraries.
The sample configuration file will be updated as the end of the development
cycle approaches. Developers should *NOT* generate the config file and propose
it as part of their patches, this will cause unnecessary conflicts.
You can generate one locally using the following command:
.. code-block:: bash
$ tox -e genconfig
The tox command will place an updated sample config in ``etc/keystone.conf.sample``.
The defaults are enough to get you going, but you can make any changes if
needed.
If there is a new external library (e.g. ``oslo.messaging``) that utilizes the
``oslo.config`` package for configuration, it can be added to the list of libraries
found in ``config-generator/keystone.conf``.

0
doc/source/devref/developing_drivers.rst → doc/source/devref/developing-drivers.rst

11
doc/source/devref/setup.rst → doc/source/devref/external-dev.rst

@ -14,9 +14,12 @@
License for the specific language governing permissions and limitations
under the License.
Setting up Keystone
===================
External Developers
===================
Get your development environment set up according to
:doc:`development_environment`. It is recommended that you install
Keystone into a virtualenv.
.. toctree::
:maxdepth: 1
services.rst
developing-drivers.rst

17
doc/source/devref/index.rst

@ -21,24 +21,15 @@ Contributor Documentation
.. toctree::
:maxdepth: 1
setup.rst
conf.rst
run-keystone.rst
initialise.rst
interact.rst
development_environment.rst
build-docs.rst
set-up-keystone.rst
http-api.rst
release-notes.rst
testing-keystone.rst
doctor-checks.rst
http-api.rst
api_change_tutorial.rst
auth-plugins.rst
database-migrations.rst
id-manage.rst
translated-responses.rst
caching-layer.rst
filtering-responsibilities.rst
list-truncation.rst
services.rst
developing_drivers.rst
architecture.rst
external-dev.rst

69
doc/source/devref/initialise.rst

@ -1,69 +0,0 @@
..
Copyright 2011-2012 OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Initializing Keystone
=====================
Before using keystone, it is necessary to create the database tables and ensures
the database schemas are up to date, perform the following:
.. code-block:: bash
$ keystone-manage db_sync
If the above commands result in a ``KeyError``, or they fail on a
``.pyc`` file with the message, ``You can only have one Python script per
version``, then it is possible that there are out-of-date compiled Python
bytecode files in the Keystone directory tree that are causing problems. This
can occur if you have previously installed and ran older versions of Keystone.
These out-of-date files can be easily removed by running a command like the
following from the Keystone root project directory:
.. code-block:: bash
$ find . -name "*.pyc" -delete
Initial Sample Data
-------------------
There is an included script which is helpful in setting up some initial sample
data for use with keystone:
.. code-block:: bash
$ ADMIN_PASSWORD=s3cr3t tools/sample_data.sh
Once run, you can see the sample data that has been created by using the
`python-openstackclient`_ command-line interface:
.. code-block:: bash
$ export OS_USERNAME=admin
$ export OS_PASSWORD=s3cr3t
$ export OS_PROJECT_NAME=admin
$ export OS_USER_DOMAIN_ID=default
$ export OS_PROJECT_DOMAIN_ID=default
$ export OS_IDENTITY_API_VERSION=3
$ export OS_AUTH_URL=http://localhost:5000/v3
$ openstack user list
The `python-openstackclient`_ can be installed using the following:
.. code-block:: bash
$ pip install python-openstackclient
.. _`python-openstackclient`: https://git.openstack.org/cgit/openstack/python-openstackclient

26
doc/source/devref/interact.rst

@ -1,26 +0,0 @@
..
Copyright 2011-2012 OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Interacting with Keystone
=========================
You can also interact with keystone through its REST API. There is a Python
keystone client library `python-keystoneclient`_ which interacts exclusively
through the REST API, and a command-line interface `python-openstackclient`_
command-line interface.
.. _`python-keystoneclient`: https://git.openstack.org/cgit/openstack/python-keystoneclient
.. _`python-openstackclient`: https://git.openstack.org/cgit/openstack/python-openstackclient

28
doc/source/devref/run-keystone.rst

@ -1,28 +0,0 @@
..
Copyright 2011-2012 OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Running Keystone
================
To run the Keystone Admin and API server instances, use:
.. code-block:: bash
$ uwsgi --http 127.0.0.1:35357 --wsgi-file $(which keystone-wsgi-admin)
This runs Keystone with the configuration the etc/ directory of the project.
See :doc:`../configuration` for details on how Keystone is configured. By default,
Keystone is configured with SQL backends.

110
doc/source/devref/development_environment.rst → doc/source/devref/set-up-keystone.rst

@ -14,18 +14,11 @@
License for the specific language governing permissions and limitations
under the License.
==========================
Setting up the Environment
==========================
.. _dev-environment:
This document describes getting the source from keystone's `Git Repository`_
and setting the environment up for development purposes.
To install keystone from packaging, refer instead to OpenStack's `User
Documentation`_.
.. _`Git Repository`: https://git.openstack.org/cgit/openstack/keystone
.. _`User Documentation`: https://docs.openstack.org/
===================
Setting up Keystone
===================
Prerequisites
=============
@ -102,8 +95,32 @@ order to run keystone:
* ``keystone.conf``
* ``keystone-paste.ini``
You can generate a sample configuration file using ``tox -e genconfig``. You
can also generate sample policy files using ``tox -e genpolicy``. Please refer
Configuring Keystone with a sample file
---------------------------------------
Keystone requires a configuration file. Keystone's sample configuration file
``etc/keystone.conf.sample`` is automatically generated based upon all of the
options available within Keystone. These options are sourced from the many
files around Keystone as well as some external libraries.
The sample configuration file will be updated as the end of the development
cycle approaches. Developers should *NOT* generate the config file and propose
it as part of their patches, this will cause unnecessary conflicts.
You can generate one locally using the following command:
.. code-block:: bash
$ tox -e genconfig
The tox command will place an updated sample config in ``etc/keystone.conf.sample``.
The defaults are enough to get you going, but you can make any changes if
needed.
If there is a new external library (e.g. ``oslo.messaging``) that utilizes the
``oslo.config`` package for configuration, it can be added to the list of libraries
found in ``config-generator/keystone.conf``.
You can also generate sample policy files using ``tox -e genpolicy``. Please refer
to :doc:`../configuration` for guidance on specific configuration options or to
view a sample paste file.
@ -132,8 +149,75 @@ following uses ``uwsgi``:
$ uwsgi --http 127.0.0.1:35357 --wsgi-file $(which keystone-wsgi-admin)
This runs Keystone with the configuration the etc/ directory of the project.
See :doc:`../configuration` for details on how Keystone is configured. By default,
Keystone is configured with SQL backends.
Database setup
==============
The script ``tools/test-setup.sh`` sets up databases as used by the
unit tests.
Initializing Keystone
=====================
Before using keystone, it is necessary to create the database tables and ensures
the database schemas are up to date, perform the following:
.. code-block:: bash
$ keystone-manage db_sync
If the above commands result in a ``KeyError``, or they fail on a
``.pyc`` file with the message, ``You can only have one Python script per
version``, then it is possible that there are out-of-date compiled Python
bytecode files in the Keystone directory tree that are causing problems. This
can occur if you have previously installed and ran older versions of Keystone.
These out-of-date files can be easily removed by running a command like the
following from the Keystone root project directory:
.. code-block:: bash
$ find . -name "*.pyc" -delete
Initial Sample Data
-------------------
There is an included script which is helpful in setting up some initial sample
data for use with keystone:
.. code-block:: bash
$ ADMIN_PASSWORD=s3cr3t tools/sample_data.sh
Once run, you can see the sample data that has been created by using the
`python-openstackclient`_ command-line interface:
.. code-block:: bash
$ export OS_USERNAME=admin
$ export OS_PASSWORD=s3cr3t
$ export OS_PROJECT_NAME=admin
$ export OS_USER_DOMAIN_ID=default
$ export OS_PROJECT_DOMAIN_ID=default
$ export OS_IDENTITY_API_VERSION=3
$ export OS_AUTH_URL=http://localhost:5000/v3
$ openstack user list
The `python-openstackclient`_ can be installed using the following:
.. code-block:: bash
$ pip install python-openstackclient
Interacting with Keystone
=========================
You can also interact with keystone through its REST API. There is a Python
keystone client library `python-keystoneclient`_ which interacts exclusively
through the REST API, and a command-line interface `python-openstackclient`_
command-line interface.
.. _`python-keystoneclient`: https://git.openstack.org/cgit/openstack/python-keystoneclient
.. _`python-openstackclient`: https://git.openstack.org/cgit/openstack/python-openstackclient

15
doc/source/devref/testing-keystone.rst

@ -23,7 +23,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`):
:ref:`dev-environment`):
.. code-block:: bash
@ -97,6 +97,19 @@ For example, to discard logging data during a test run:
$ OS_LOG_CAPTURE=0 tox -e py27
Building the Documentation
--------------------------
The documentation is generated with Sphinx using the tox command. To create HTML
docs and man pages:
.. code-block:: bash
$ tox -e docs
The results are in the ``doc/build/html`` and ``doc/build/man`` directories
respectively.
Tests Structure
---------------