Open Stack

We released a new os-api-ref yesterday which includes a few
enhancements, including the anchor links on the website working as
expected now.

One of the things in there is a new warning when a parameter is used,
and is not defined.

https://github.com/openstack/keystone/blob/bc8a145de14e455a2a73824e8a84d92ac27aae1c/api-ref/source/v2-ext/ksec2-admin.inc#L31
- as an example

Which will generate an issue such as:

Warning, treated as error:
/home/sdague/code/openstack/keystone/api-ref/source/api-ref/source/v2-ext/ksec2-admin.inc:112
.rst:: WARNING: No path parameter ``userId`` found in rest_parameter stanza.


Long term, these really all need to be fixed, because this is specifying
a parameter and giving the user no expectation about what it is and how
it is used.

In the short term, if this is too hard for teams to address, remove the
'-W' from the sphinx_build line in your api-ref section, then work
through the warnings, and make warnings enforcing when done.

I've seen fails on keystone. But there may be fails other places as well.

Keystone fix is here - https://review.openstack.org/#/c/423387 as an
example of what might be needed to move forward for projects.

	-Sean

-- 
Sean Dague
http://dague.net