Switch to openstackdocstheme 2.2.1 version. Using
this version will allow especially:
* Linking from HTML to PDF document
* Allow parallel building of documents
* Fix some rendering problems
Update Sphinx version as well.
Disable openstackdocs_auto_name to use 'project' variable as name.
Change pygments_style to 'native' since old theme version always used
'native' and the theme now respects the setting and using 'sphinx' can
lead to some strange rendering.
openstackdocstheme renames some variables, so follow the renames
before the next release removes them. A couple of variables are also
not needed anymore, remove them.
See also
http://lists.openstack.org/pipermail/openstack-discuss/2020-May/014971.html
Change-Id: I30bdb1bf76a12e9562ab461b2701a36f34e770fe
As an expansion of the guidelines around microversions, add guidelines
around how services should expose Version Discovery documents. This
includes recommendations for putting unversioned endpoints into the
catalog.
It also includes a completely new thought, so feel free to punch me in
the head - that versioned discovery documents should include a
collections rel link to allow clients to get from the versioned to the
universioned document without having to do URL manipulation. If we can
get that in, it should serve as a bridge for those clouds that are still
putting versioned endpoints into the catalog for a while for backwards
compat reasons.
Two related follow-up patches are in-work. One that adds a copy of the
consuming-discovery document with all of the extra effort in support of
clouds and services that to not implement these guidelines removed, so a
"perfect future state" is easy to read. The other is a document
recommending a global cloud "profile" that greatly reduces the API
burden on clients consuming this information.
Change-Id: Id8160048dfffc1ada32ce876a65b02fb7a02306e
The next patch actually describes desired state of version discovery.
But in an epic amount of cart-before-the-horse, we have the process for
consuming the discovery already because the process must take in to account
the present as well as the past. This process has kept in mind what consuming
the recommended discovery process _wants_ to look like in the future and in
calls that out in a few places. The intent would be that the algorithm here
would work for all clouds, but that as clouds and services adopt API-SIG
recommendations, the interactions with the clouds would become more
efficient. (so for clients using the complete algorithm they should be
upwards compatible with forthcoming API-SIG guidelines and will just
naturally do less work over time).
I believe this is consistent in defaults, fallbacks and error conditions with
what is currently implemented in keystoneauth, although there is
additional logic presented here which is not yet in keystoneauth. The
intent is for the process presented here to not change the behavior
experienced by current keystoneauth users, with the exception that when
the complete algorithm is implemented it's possible that an additional
API call may be made on older clouds. That is to say, keystoneauth
should not need to make any incompatible changes, but may need to add
some features to be a fully compliant implementation.
Apologies for the size and complexity. It turns out there are many
historical oddities still lurking out there and advice to client
authors that does not take them in to account would be incomplete. On
the other hand, as we drive guidelines forward into being implemented,
the need for this much crazy logic should go away.
Co-Authored-By: Dmitry Tantsur <divius.inside@gmail.com>
Change-Id: I241f76bca8ac27fc3d27028ae284b9012a2da7e9
This repo is now testing only with Python 3, so let's make
a few cleanups:
- Remove obsolete sections from setup.cfg
- Update requirements, no need for python_version anymore
- Use newer openstackdocstheme version, update other requirements
Change-Id: I2aec09250c96bc411d19cb6c1a1ee852394d39e5
The default for install_command is good, no need to add our own version
in tox.ini. Remove it.
Remove git commands from conf.py, current openstackdocstheme handles
this itself.
Fix some missed api-wg -> api-sig renames in conf.py.
Change-Id: I806e804a5852e081f0cb8c1b43ffe13a119aba2c
This fixes building the guidelines (again) since Sphinx 2.0.0 is not
compatible with Python 2.7, and the way we use basepython in tox.ini
is not correct (resulting in Python 2 being used by default).
Change-Id: Ieeeb319caa6d7a8dad78857c7dce105da33d2dd2
David Stanek isn't involved in keystone any more, so I am designating
myself as the liaison for keystone.
Change-Id: I2d396c9dad31a041ae86755c2ff3caf26f096bae
Added myself as the Placement liaison to the API-SIG. There was also an
empty duplicate section for Nova in the file, so I removed that.
Change-Id: I6701a06b8b0a70a2fe010cbd340ef5e6bc2520a7
The recent yasfb is not compatible with ancient sphinx, just bump
both requirements, as well as replace deprecated oslosphinx with
openstackdocstheme (requirements shamelessly copied from ironic-specs).
While we're here, uncap pbr and bump it to 1.0.
Change-Id: Ia78499827a53f5ee0c7a8b0d9951a0e37dedc91b
We want to default to running all tox environments under python 3, so
set the basepython value in each environment.
We do not want to specify a minor version number, because we do not
want to have to update the file every time we upgrade python.
We do not want to set the override once in testenv, because that
breaks the more specific versions used in default environments like
py35 and py36.
Change-Id: I19c77a2604de964672e22780bf0ae8c5874beede
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
In a recent api-sig meeting it was decided that we should link
to this document as a good introduction and commentary on best
practices.
Change-Id: I662ed5c9c21a6eafb74cd1e224bf8c8953a556b6
In the opening we advise people to use the HTTP RFCs as the ultimate
authority but do not link to them. This change adds the links and
generalizes the warning to the entirety of the guidelines, not just
to non-JSON apis.
Change-Id: I40a59594a477d6802a16d8b0ca11020629eff292
This is a mechanically generated patch to complete step 1 of moving
the zuul job settings out of project-config and into each project
repository.
Because there will be a separate patch on each branch, the branch
specifiers for branch-specific jobs have been removed.
Because this patch is generated by a script, there may be some
cosmetic changes to the layout of the YAML file(s) as the contents are
normalized.
See the python3-first goal document for details:
https://governance.openstack.org/tc/goals/stein/python3-first.html
Change-Id: Id70bf989245c247bdcff0b0cdf0c40e12e58afb8
Story: #2002586
Task: #24760
Links to the wiki and git were out of date.
Also update .gitreview to reflect new repository name.
Change-Id: I950604740b7ef8d8ec0b1f97499bdc6e6648db0e
According to Openstack summit session [1],
stestr is maintained project to which all Openstack projects should migrate.
Let's switch to stestr as other projects have already moved to it.
[1] https://etherpad.openstack.org/p/YVR-python-pti
Change-Id: Iddce63084a10cbc5b1670f42acae6c2ee96e0ce8
Add '_' as a valid character in error.codes, because that's what's
present in the wild.
The schema is updated to include a pattern check, and one of the
examples is changed to demonstrate the use of the new char.
Change-Id: I6bcfd5d411b2b9c540546f92859647333114a8f8
They've been TODO for a long time. The provided links are
examples only, but include advice that services should publish
their own error code documentation.
Change-Id: I8e80160abc51ace34e8e286defc9ebe6a7847d54
Story: 1593321
Task: 22178
Based on conversation in IRC http://p.anticdent.org/282V , update
the errors guideline to be more specific about:
* using specific codes for specific cases
* adding errors is okay and not a breaking-change
Change-Id: I473918ce9c6b49c0b904e93b7140421525f4e7c0
This adds some practical guidance to the existing section on caching
to make it clear that where responses are not making explicit
assertions about controlling cache, they MUST "cache-control: no-cache"
Change-Id: If13a5a19ff077cd9a2c9c400c24af70ea6f818d9
Closes-Bug: #1747935
The test for file extensions was checking everything returned by
glob.glob("guidelines/*"). The recent merge of the refactored HTTP
guidelines added a new guidelines/http/ directory, and the test was
failing because that entry didn't end with either .rst or .json. This
patch corrects that by skipping directories from that name check.
Change-Id: I0a84160015e9c1d96cb456b07c5e45fc6645df08
The current HTTP guideline is very, very large. It will be more easily
discovered and consumed by breaking it up into logical chunks.
Co-Authored-By: Dmitry Tantsur <dtantsur@redhat.com>
Change-Id: I964b1f31e50c93f59e5dc07d7643c6c21b51f762