diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5990dc1e..1bc7478d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,10 +1,10 @@ If you would like to contribute to the development of oslo's libraries, -first you must take a look to this page: +first you must take a look at this page: https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html If you would like to contribute to the development of OpenStack, -you must follow the steps in this page: +you must follow the steps on this page: https://docs.openstack.org/infra/manual/developers.html diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index cf29f0bb..2de07807 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -3,7 +3,7 @@ ======================= oslo.policy uses oslo.config to define and manage configuration options -to allow the deployer to control where the policy files are located and -the default rule to apply when policy etc. +that allow the deployer to control where the policy files are located, +the default rule to apply, etc. .. show-options:: oslo.policy diff --git a/doc/source/user/plugins.rst b/doc/source/user/plugins.rst index 9638cd81..78ae67d6 100644 --- a/doc/source/user/plugins.rst +++ b/doc/source/user/plugins.rst @@ -35,7 +35,7 @@ entry point and will try to invoke that stevedore plugin. This mechanism allows anyone to write their own code, in their own library with their own custom stevedore based rule check plugins and can enhance their policies with custom checks. This would be useful for example to -integrate with a in-house policy server. +integrate with an in-house policy server. Example code - HttpCheck diff --git a/doc/source/user/sphinxpolicygen.rst b/doc/source/user/sphinxpolicygen.rst index e39f70a1..227dbad8 100644 --- a/doc/source/user/sphinxpolicygen.rst +++ b/doc/source/user/sphinxpolicygen.rst @@ -23,7 +23,7 @@ where: ``policy_generator_config_file`` Path to an configuration file used with the ``oslopolicy-sample-generator`` - utility. This can be an full path or a value relative to the documentation + utility. This can be a full path or a value relative to the documentation source directory (``app.srcdir``). If this option is not specified or is invalid then the sample policy file generation will be skipped. @@ -34,8 +34,8 @@ where: ``sample_policy_basename`` Base name of the output file. This name will be appended with a - ``.policy.yaml.sample`` extension to generate the final output file and the - path is relative to documentation source directory (``app.srcdir``). As such, + ``.policy.yaml.sample`` extension to generate the final output file, and the + path is relative to the documentation source directory (``app.srcdir``). As such, using the above example, the policy file will be output to ``_static/nova.policy.yaml.sample``. If this option is not specified, the file will be output to ``sample.policy.yaml``. diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index b8ea7f03..6bbee5f7 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -19,8 +19,8 @@ Incorporating oslo.policy tooling The ``oslo.policy`` library offers a generator that projects can use to render sample policy files, check for redundant rules or policies, among other things. -This is a useful tool not only for operators managing policies, but also -developers looking to automate documentation describing the projects default +This is a useful tool not only for operators managing policies but also for +developers looking to automate documentation describing projects' default policies. This part of the document describes how you can incorporate these features into @@ -39,7 +39,7 @@ First, you'll need to expose a couple of entry points in the project's foo = foo.common.policy:get_enforcer The ``oslo.policy`` library uses the project namespace to call ``list_rules``, -which should return a list of ``oslo.policy`` objects, either instances of +which should return a list of ``oslo.policy`` objects, instances of either ``RuleDefault`` or ``DocumentedRuleDefault``. The second entry point allows ``oslo.policy`` to generate complete policy from @@ -129,7 +129,7 @@ benefits. providing better documentation. * A sample policy file can be generated based on the registered policies - rather than needing to manually maintain one. + rather than needing to be manually maintained. * A policy file can be generated which is a merge of registered defaults and policies loaded from a file. This shows the effective policy in use. @@ -174,7 +174,7 @@ class:: The `DocumentedRuleDefault` class inherits from the `RuleDefault` implementation, but it must be supplied with the `description` attribute in order to be used. In addition, the `DocumentedRuleDefault` class requires a new -`operations` attributes that is a list of dictionaries. Each dictionary must +`operations` attribute that is a list of dictionaries. Each dictionary must have a `path` and a `method` key. The `path` should map to the path used to interact with the resource the policy protects. The `method` should be the HTTP verb corresponding to the `path`. The list of `operations` can be supplied with @@ -269,9 +269,9 @@ Putting it all together ~~~~~~~~~~~~~~~~~~~~~~~ Now that you know what services types, resources, attributes, and actions are -within the context of policy names, let establish the order you should use -them. Policy names should increase in detail as you read it. This results in -the following syntax:: +within the context of policy names, it is possible to establish the order you +should use them. Policy names should increase in detail as you read it. This +results in the following syntax:: :[:][:]:[:] @@ -341,7 +341,8 @@ for a user with a project-scoped token to access a system-level API. Developers incorporating `scope_types` into OpenStack services should be mindful of the relationship between the API they are protecting with a policy -and if it operates on system-level resources or project-level resources. +and the resource level the API operates at, whether it's system-level or +project-level. Sample file generation ---------------------- @@ -475,7 +476,7 @@ which determines if a user is allowed to do something. The coupling between the authorization context, ultimately the token, and the policy enforcement mechanism raises the bar for effectively testing policies and APIs. Service developers want to ensure the functionality specific to their -service works, and not dwell on the implementation details of an authorization +service works and not dwell on the implementation details of an authorization system. Additionally, they want to keep unit tests lightweight, as opposed to requiring a separate system to issue tokens for authorization, crossing the boundary of unit testing to integration testing.