This reorder's parameters.yaml to the correct sort order, and turns
the info message about incorrect ordering into a warning. After this
lands parameters.yaml changes will always require that the items stay
in the sorted order enforced by the extension.
Part of bp:api-ref-in-rst
Change-Id: Ib890d369a8b50a8cd920f7b19ef13f44b3e657df
This puts in the infrastructure for enforcing the section and
parameter name ordering in parameters.yaml file. It does so through
loading the lookup table as an ordered dict, and doing compare
operations to it during initial load.
The ordered dict loading is far more expensive than straight stream
loading, so a cache mechanism for file => loaded yaml is also
added. This reduces the sphinx build time to less than it was
previously, even though we are doing more processing of the data.
Once the parameters.yaml file is made compliant, we can move these
from .info to .warn and enforce the file stays alphabetized.
Part of bp:api-ref-in-rst
Change-Id: Id30464d6326aec3ed7d82c178261d686e2509d33
The Glance gate pep8 job believes that there's a violation of E126
(continuation line over-indented for hanging indent). This patch
reduces the indent by 1 space so the pep8 job will be happy.
Change-Id: Idc946cb14c4b1dddc6a425ffbb6b4b3f1609a4ec
This removes the final warnings from the api-ref code base, and flips
the sphinx switch to enforce warnings as errors.
It also adds code to the rest_parameters extension to make it more
clear where a problem is when it comes to included parameters. This
puts us in a place where we can start doing the file per file look at
content.
Part of bp:api-ref-in-rst
Change-Id: Ic2c99d96d6addcafa00b9f16785c2fe59b1798d3
This adds a global control that does show / hide of all collapseable
sections. Which is extremely useful in seeing the entire API at once.
Part of bp:api-ref-in-rst
Change-Id: I814e6b2c20c25bf3d4cb4e722bc8157ca0aa1b89
In swagger the attribute for required/optional is 'required', so we've
decided that's a better way to specify our parameters. This changes
the sphinx parser to use that when inserting (optional) into the
table.
We also make all 'path' parameters required, because we never specify
them in a table where they are not. I think them all being required:
false was an artifact of the data processing.
Part of bp:api-ref-in-rst
Change-Id: Ie2d012741d69430546fe1b10c9f16c853acb926a
In working on converting data over to this new format, it will often
show up dirty with things like a broken reference to the parameters
file. We can make the parser be a bit more robust to these errors and
explain what is going on both in a warning, and in the final document.
Change-Id: I9cd44bddffadd20bfe4f3c12f2102f7e9a69c909
Instead of throwing a KeyError if the lookup file isn't what we
expected, and dying, throw a warning and skip the key in content. This
makes it a bit easier to understand what's wrong and how to address it
for people not familiar with the code.
Change-Id: I0d1cb60b5a1010d00e5290f697bbde601fd5f221
This creates a stub for landing content to support having the source
for the api-ref site in our source tree. It includes a new sphinx
extension that will be used to generate the html needed for the site
which supports 2 new stanzas:
.. rest_parameters::
This uses a parameters yaml file to look up the definitions of
parameters and produce a structured table of those parameters and how
they are used.
.. rest_method::
This is a stanza used inside a section which specifies the REST method
(i.e. GET /servers/{id}) which is then used to produce a nice
collapsable section.
This uses quite a bit of the sphinx extension API, and tries to
document any non obvious actions.
This extension needs additional styling from bootstrap, and some
custom js / css to do the theming / collapsing. That's included as
part of this.
Change-Id: I41b568b782d3c85f6ef8d3bb3a6f4ae378e4dc33
Sean Dague