Open Stack

I can't believe that this is caused by a rather simple rst file. My
environment must be incompatible somewhere. I use virtualenv as well, then
pip install tox+sphinx+openstackdocstheme, then tox -e docs. 

The file is below if you are really interested. In any case, I have just
uploaded it to Gerrit (https://review.openstack.org/#/c/166853/2), so that
there is some content for review. My build problems can be resolved
separately.

Thanks for all the suggestions.

Bernd

Policy.json document:

====================
The policy.json file
====================

The policy.json file contains a list of policy rules, each setting the 
conditions for permitting an action, typically an API request.

Whether a user is allowed to carry out a request depends on the request
itself,
the target object of the request and the user making the request.

General form:

.. code::

   action : access condition

Access conditions can be:

* always true, so that the action is permitted. This can be written as 
  ``""`` (empty string), ``[]``, or ``"@"``.
* always false, so that the action is not allowed. Written as ``"!"``.
* a comparison of two values
* complex conditions formed with boolean operators ``not``, ``and``, ``or`` 
  and parentheses
* aliases, using the ``rule`` keyword.

Two values are compared in the following way

.. code::

   value1 : value2

Possible values are

* constants: Strings, numbers, ``true``, ``false``
* attributes of the user making the request
* attributes of the target object
* API attributes
* the flag ``is_admin``

User attributes can be ``project_id``, ``user_id``, ``domain_id`` or
``role``.

Target object attributes are database fields. Example: ``%(project_id)s``
means the tenant (project) that owns the object. The trailing ``s``
indicates 
this is a string.

This example compares the user ID of the user making the request with
the user ID of the target object

.. code::

   user_id : %(user_id)s

An alias is shorthand for a complex or hard to understand access condition. 
It is defined in the same way as an access rule

.. code::

   alias name : access condition

Once an alias is defined, use the ``rule`` keyword to use it in a policy
rule.
See examples below.

    
Examples
~~~~~~~~

Unconditionally grant permission to create an instance:

.. code::

   "compute:create": ""

Disable shelving of an instance, perhaps as a temporary measure or because
you
don't want users to be able to shelve instances at all:

.. code::

   "compute:shelve": "!"

Define an alias for the condition "target object's user_id is equal to
user's 
user_id", which means that the user owns the object. The condition features
a 
user attribute ``user_id`` and a target object attribute ``%(user_id)s``:

.. code::

   "owner" : "user_id:%(user_id)s",

Define an alias for "user is administrator or owns the object". It is based 
on two previously defined aliases, combined with ``or``:

.. code::

   "admin_or_owner": "rule:admin_required or rule:owner",

Another definition for ``admin or owner``. Here the user's tenant ID is
compared
with the target object's tenant ID. The definition also uses a constant
value
``True``:

.. code::

   "admin_or_owner":  "is_admin:True or project_id:%(project_id)s"
    
This is how an alias is used:

.. code::

   "compute:start": "rule:admin_or_owner"

Here, only the administrator or the owner
of an instance are allowed to start it.

A slightly more complex condition demonstrating the use of boolean
expressions.
To delete an EC2 credential, an Identity service API, one must either be 
administrator, or both own the credential and have a matching user ID:

.. code::

   "identity:ec2_delete_credential": "rule:admin_required or 
         (rule:owner and user_id:%(target.credential.user_id)s)"

Older syntax
~~~~~~~~~~~~

Older policy.json files may feature a different syntax not based on boolean
expressions but nested JavaScript arrays. 
For example, the EC2 credentials condition above would have been written as 
follows:

.. code::

   "identity:ec2_delete_credential": [ [ "rule:admin_required ], 
         [ "rule:owner", "user_id:%(target.credential.user_id)s)" ] ]

The condition is an array of arrays. The innermost arrays are or'ed
together,
whereas elements inside the innermost arrays are and'ed.

While the old syntax is still supported, we recommend using the newer, more
intuitive syntax.

# end of file

-----Original Message-----
From: Christian Berendt [mailto:christian at berendt.io] 
Sent: Monday, March 23, 2015 9:27 PM
To: openstack-docs at lists.openstack.org
Subject: Re: [OpenStack-docs] Sphinx error when building in
openstack-manuals

On 03/23/2015 11:21 AM, Bernd Bausch wrote:
> 1- add policy.rst to 
> openstack-manuals/doc/playground-user-guide/source
> 2- add it to the table of contents in index.rst
> 3- in the source directory, "sphinx-build -b html . my-output-directory"

The following is working for me to build the playground-user-guide. Can you
please share your policy.rst file.

git clone https://github.com/openstack/openstack-manuals
cd openstack-manuals
virtualenv .venv
source .venv/bin/activate
pip install -r test-requirements.txt
cd doc/playground-user-guide/source
mkdir build
sphinx-build -b html . build

HTH, Christian.

--
Christian Berendt
Cloud Solution Architect
Mail: berendt at b1-systems.de

B1 Systems GmbH
Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537

_______________________________________________
OpenStack-docs mailing list
OpenStack-docs at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs