Configuration guide references configuration options for policy instead of sample policy file

[Lance Bragstad]

The configuration guide document should contain all information for configuration options, as well as sample policy files. Keystone's configuration section uses the wrong directive, which results in the configuration options being rendered where the sample policy file should be:

https://docs.openstack.org/keystone/latest/configuration/policy.html

We should correct this so that the policy section of the configuration guide references policy and not configuration options.

[Lance Bragstad (lbragstad)]

Patch up for review - https://review.openstack.org/#/c/488508/

[Lance Bragstad (lbragstad)]

Adding oslo.policy because of a couple things Doug and I ran into while debugging this. Full discussion is available in IRC logs [0]. The oslo.policy bits boil down to the following:

 - the show-policy directive fails to error when the config doesn't exist
 - empty strings as default policies causes the rst parser to think ```` is an underline or overline

Doug has a couple patches proposed to oslo.policy to fix these issues [1][2]. Once those land and we get a fixed lib, we should be able to use the show-policy directive in keystone to render the sample configuration file for the configuration guide.

[0] http://eavesdrop.openstack.org/irclogs/%23openstack-dev/%23openstack-dev.2017-07-28.log.html#t2017-07-28T16:33:01
[1] https://review.openstack.org/#/c/488546/
[2] https://review.openstack.org/#/c/488547/

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/488546
Committed: https://git.openstack.org/cgit/openstack/oslo.policy/commit/?id=2b99c39c30df432fe79cbfe3db0f21039e324fb4
Submitter: Jenkins
Branch: master

commit 2b99c39c30df432fe79cbfe3db0f21039e324fb4
Author: Doug Hellmann <email address hidden>
Date: Fri Jul 28 13:35:33 2017 -0400

    fix formatting for empty defaults

    When the default for a policy rule is empty, the output is ````. The
    rst parser interprets that as a title overline or underline, and
    sphinx dies. When we have no default rule emit a string saying so to
    avoid emitting an empty literal inline block.

    Closes-Bug: 1707246
    Change-Id: I774b2de5ff59874dfa67811c094735dd74c8083e
    Signed-off-by: Doug Hellmann <email address hidden>

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/488547
Committed: https://git.openstack.org/cgit/openstack/oslo.policy/commit/?id=4b2342a9fe71ca47282b302372df594157c5da2f
Submitter: Jenkins
Branch: master

commit 4b2342a9fe71ca47282b302372df594157c5da2f
Author: Doug Hellmann <email address hidden>
Date: Fri Jul 28 13:37:12 2017 -0400

    throw an exception when sphinxext cannot find the config file

    Using the app error function is not enough to break the build at the
    point where the error occurs. Throw an exception with an error message
    explaining the problem.

    Related-Bug: 1707246
    Change-Id: Ie836b7a6f3ea7cba1737913b944f36c77f14cfd0
    Signed-off-by: Doug Hellmann <email address hidden>

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/pike
Review: https://review.openstack.org/489372

[OpenStack Infra (hudson-openstack)]

Related fix proposed to branch: stable/pike
Review: https://review.openstack.org/489373

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/489373
Committed: https://git.openstack.org/cgit/openstack/oslo.policy/commit/?id=3cbcaad8a44f913aea4b31aa3184410b0b227868
Submitter: Jenkins
Branch: stable/pike

commit 3cbcaad8a44f913aea4b31aa3184410b0b227868
Author: Doug Hellmann <email address hidden>
Date: Fri Jul 28 13:37:12 2017 -0400

    throw an exception when sphinxext cannot find the config file

    Using the app error function is not enough to break the build at the
    point where the error occurs. Throw an exception with an error message
    explaining the problem.

    Related-Bug: 1707246
    Change-Id: Ie836b7a6f3ea7cba1737913b944f36c77f14cfd0
    Signed-off-by: Doug Hellmann <email address hidden>
    (cherry picked from commit 4b2342a9fe71ca47282b302372df594157c5da2f)

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/489372
Committed: https://git.openstack.org/cgit/openstack/oslo.policy/commit/?id=45cd69557df98f8ccc581be0e6eaab3954310aaf
Submitter: Jenkins
Branch: stable/pike

commit 45cd69557df98f8ccc581be0e6eaab3954310aaf
Author: Doug Hellmann <email address hidden>
Date: Fri Jul 28 13:35:33 2017 -0400

    fix formatting for empty defaults

    When the default for a policy rule is empty, the output is ````. The
    rst parser interprets that as a title overline or underline, and
    sphinx dies. When we have no default rule emit a string saying so to
    avoid emitting an empty literal inline block.

    Closes-Bug: 1707246
    Change-Id: I774b2de5ff59874dfa67811c094735dd74c8083e
    Signed-off-by: Doug Hellmann <email address hidden>
    (cherry picked from commit 2b99c39c30df432fe79cbfe3db0f21039e324fb4)

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/oslo.policy 1.25.1 release.

[Lance Bragstad (lbragstad)]

Now that oslo.policy 1.25.1 is out the door - we should be able to fix keystone once we get the requirements bump.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/488508
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=fffc84db79fabb2bb35367387dd4b19e9dafb6d1
Submitter: Jenkins
Branch: master

commit fffc84db79fabb2bb35367387dd4b19e9dafb6d1
Author: Doug Hellmann <email address hidden>
Date: Fri Jul 28 12:06:12 2017 -0400

    use the show-policy directive to show policy settings

    Closes-Bug: 1707246

    Depends-On: I774b2de5ff59874dfa67811c094735dd74c8083e
    Depends-On: Ie836b7a6f3ea7cba1737913b944f36c77f14cfd0
    Change-Id: I5ce0931d39b045681ba6d43d7894ae25e6b13146
    Signed-off-by: Doug Hellmann <email address hidden>

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/keystone 12.0.0.0rc1 release candidate.

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/oslo.policy 1.26.0 release.