openstack
/
os-api-ref
Code Issues Proposed changes
Sphinx extension to support OpenStack API reference pages creation
177 Commits 1 Branch 19 Tags 1.5 MiB
Python 69.6%
JavaScript 25.3%
CSS 5.1%
Go to file
Rafael Weingärtner 3d4f056ca3 Fix exception logging 
When an exception happens while executing the method `_load_param_file`,
the exception logging `LOG.exception(exc_info=exc)` will generate an
error.

A small snippet to reproduce the issue is the following code:

  from sphinx.util import logging

  LOG = logging.getLogger(__name__)

  try:
      raise Exception("teste")
  except Exception as exc:
      LOG.exception(exc_info=exc)

Which will generate the error:

  Exception: teste

  During handling of the above exception, another exception occurred:

  Traceback (most recent call last):
    File "/home/rafael/git/os-api-ref/os_api_ref/test-logging.py", line 8, in <module>
      LOG.exception(exc_info=exc)
  TypeError: exception() missing 1 required positional argument: 'msg'

  Process finished with exit code 1

With this fix, the exception logging error is solved, and users get a
meaningful message.

Change-Id: Ib3c3e93c283d86b9708c74e60c2ac5762dc2c222
 		2021-10-21 10:16:39 +01:00
doc Drop support for Sphinx < 4.x 2021-10-21 10:14:22 +01:00
os_api_ref Fix exception logging 2021-10-21 10:16:39 +01:00
.coveragerc Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
.gitignore General overhaul of testing setup 2018-06-18 14:36:12 +01:00
.gitreview OpenDev Migration Patch 2019-04-19 19:26:32 +00:00
.mailmap Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
.pre-commit-config.yaml Move flake8 as a pre-commit local target. 2021-03-23 13:15:01 +01:00
.stestr.conf General overhaul of testing setup 2018-06-18 14:36:12 +01:00
.zuul.yaml Switch testing to Xena testing runtime 2021-04-30 15:04:30 +08:00
CONTRIBUTING.rst Update and replace http with https for doc links 2017-12-22 07:37:46 +00:00
HACKING.rst Update and replace http with https for doc links 2017-12-22 07:37:46 +00:00
LICENSE Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
README.rst Replace git.openstack.org URLs with opendev.org URLs 2019-04-25 16:31:25 +00:00
RELEASING.rst add file on releasing the software 2017-01-20 15:54:39 -05:00
TESTS.rst add a list of tests we should have 2016-05-27 16:04:12 -04:00
requirements.txt Remove six 2021-10-21 10:14:26 +01:00
setup.cfg setup.cfg: Replace dashes with underscores 2021-05-14 16:05:53 +08:00
setup.py Updated from global requirements 2017-03-03 00:02:21 +00:00
test-requirements.txt Fix hacking min version to 3.0.1 2020-10-06 17:53:57 +08:00
tox.ini tox: Don't use distutils entrypoint for coverage 2021-10-21 10:15:17 +01:00

README.rst

Team and repository tags

image

os-api-ref

Sphinx Extensions to support API reference sites in OpenStack

This project is a collection of sphinx stanzas that assist in building an API Reference site for an OpenStack project in RST. RST is great for unstructured English, but displaying semi structured (and repetitive) data in tables is not its strength. This provides tooling to insert semi-structured data describing request and response parameters and status or error messages, and turn those into nice tables.

The project also includes a set of styling (and javascript) that is expected to layer on top of a Sphinx theme base. This addition provides a nice set of collapsing sections for REST methods and javascript controls to expand / collapse all sections.

Features

  • Sphinx stanza rest_method describing the method and resource for a REST API call. Lets authors write simply and also gives readers a clean way to scan all methods then click a button to get more information about a method.
  • Sphinx stanza rest_parameters used to insert semi-structured data into the RST files describing the parameters users can send with the request. The stanza points to a structured YAML file, parameters.yaml.
  • Sphinx stanza rest_status_code used to insert pointers to error or status codes returned by the service. Points to a structured YAML file, http_codes.yaml.

TODO

A list, in no particular order, of things we should do in this project. If you would like to contribute to any of these please show up in #openstack-dev on IRC and ask for sdague or mugsie to discuss or send an email to the openstack-discuss@lists.openstack.org list with [api] in the subject line.

  • Enhance documentation with more examples and best practices
  • Testing for the code
  • max_microversion parameter support - so that we automatically tag parameters that have been removed
  • Make a microversion selector, so that you can get a version of the api-ref that hides all microversion elements beyond your selected version (this one is going to be a bit of complex javascript), in progress.

Potential ideas

These aren't even quite todos, but just ideas about things that might be useful.

  • .. literalinclude is good for API samples files to be included, but should we have more markup that includes the full REST /URL as well.

Sphinx stanzas

rest_method: Enter the REST method, such as GET, PUT, POST, DELETE, followed by the resource (not including an endpoint) for the call. For example:

.. rest_method:: PUT /v2/images/{image_id}/file

rest_parameters: Enter a reference to a parameters.yaml file and indicate which parameter you want to document. For example:

.. rest_parameters:: images-parameters.yaml

   - Content-type: Content-Type-data
   - image_id: image_id-in-path

Where the images-parameters.yaml file contains pointers named Content-type and image_id and descriptions for each.

rest_status_code: Enter a reference to a http-status.yaml file and indicate which errors or status codes you want to document. You can also add a pointer to more precise descriptions for each code. For example:

.. rest_status_code:: success http-codes.yaml

  - 204

.. rest_status_code:: error http-codes.yaml

  - 400: informal
  - 401
  - 403
  - 404
  - 409
  - 410: image-data-410
  - 413: image-data-413
  - 415: image-data-415
  - 500: informal
  - 503: image-data-503