========================
Team and repository tags
========================
.. image:: https://governance.openstack.org/tc/badges/os-api-ref.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
.. Change things from this point on
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
* Free software: Apache license
* Documentation: https://docs.openstack.org/os-api-ref/latest/
* Source: https://opendev.org/openstack/os-api-ref
Raw data
{
"_id": null,
"home_page": "https://docs.openstack.org/os-api-ref/latest/",
"name": "os-api-ref",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "OpenStack",
"author_email": "openstack-discuss@lists.openstack.org",
"download_url": "https://files.pythonhosted.org/packages/00/70/cb40fcbbc647e2f6fa8a1e8ca56d994604832055b0427466a8c65f0b8299/os-api-ref-3.0.1.tar.gz",
"platform": null,
"description": "========================\nTeam and repository tags\n========================\n\n.. image:: https://governance.openstack.org/tc/badges/os-api-ref.svg\n :target: https://governance.openstack.org/tc/reference/tags/index.html\n\n.. Change things from this point on\n\nos-api-ref\n==========\n\nSphinx Extensions to support API reference sites in OpenStack\n\nThis project is a collection of sphinx stanzas that assist in building\nan API Reference site for an OpenStack project in RST. RST is great\nfor unstructured English, but displaying semi structured (and\nrepetitive) data in tables is not its strength. This provides tooling\nto insert semi-structured data describing request and response\nparameters and status or error messages, and turn those into nice tables.\n\nThe project also includes a set of styling (and javascript) that is\nexpected to layer on top of a Sphinx theme base. This addition\nprovides a nice set of collapsing sections for REST methods and\njavascript controls to expand / collapse all sections.\n\nFeatures\n--------\n\n* Sphinx stanza ``rest_method`` describing the method and resource for a REST\n API call. Lets authors write simply and also gives readers a clean way to\n scan all methods then click a button to get more information about a method.\n* Sphinx stanza ``rest_parameters`` used to insert semi-structured data into\n the RST files describing the parameters users can send with the request. The\n stanza points to a structured YAML file, ``parameters.yaml``.\n* Sphinx stanza ``rest_status_code`` used to insert pointers to error or status\n codes returned by the service. Points to a structured YAML file,\n ``http_codes.yaml``.\n\nTODO\n----\n\nA list, in no particular order, of things we should do in this\nproject. If you would like to contribute to any of these please show\nup in ``#openstack-dev`` on IRC and ask for ``sdague`` or ``mugsie``\nto discuss or send an email to the openstack-discuss@lists.openstack.org list\nwith [api] in the subject line.\n\n* Enhance documentation with more examples and best practices\n* Testing for the code\n* ``max_microversion`` parameter support - so that we automatically\n tag parameters that have been removed\n* Make a microversion selector, so that you can get a version of the api-ref\n that hides all microversion elements beyond your selected version\n (this one is going to be a bit of complex javascript), in progress.\n\nPotential ideas\n~~~~~~~~~~~~~~~\n\nThese aren't even quite todos, but just ideas about things that might\nbe useful.\n\n* ``.. literalinclude`` is good for API samples files to be included,\n but should we have more markup that includes the full ``REST /URL``\n as well.\n\n\nSphinx stanzas\n--------------\n\n**rest_method**: Enter the REST method, such as GET, PUT, POST, DELETE,\nfollowed by the resource (not including an endpoint) for the call. For\nexample::\n\n .. rest_method:: PUT /v2/images/{image_id}/file\n\n**rest_parameters**: Enter a reference to a ``parameters.yaml`` file and\nindicate which parameter you want to document. For example::\n\n .. rest_parameters:: images-parameters.yaml\n\n - Content-type: Content-Type-data\n - image_id: image_id-in-path\n\nWhere the ``images-parameters.yaml`` file contains pointers named\n``Content-type`` and ``image_id`` and descriptions for each.\n\n**rest_status_code**: Enter a reference to a ``http-status.yaml`` file and\nindicate which errors or status codes you want to document. You can also add\na pointer to more precise descriptions for each code. For example::\n\n .. rest_status_code:: success http-codes.yaml\n\n - 204\n\n .. rest_status_code:: error http-codes.yaml\n\n - 400: informal\n - 401\n - 403\n - 404\n - 409\n - 410: image-data-410\n - 413: image-data-413\n - 415: image-data-415\n - 500: informal\n - 503: image-data-503\n\n\n* Free software: Apache license\n* Documentation: https://docs.openstack.org/os-api-ref/latest/\n* Source: https://opendev.org/openstack/os-api-ref\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Sphinx Extensions to support API reference sites in OpenStack",
"version": "3.0.1",
"project_urls": {
"Homepage": "https://docs.openstack.org/os-api-ref/latest/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a1aec369a49deb45985237909629dff8594df080b5a40ed52def86c064059a5",
"md5": "ebc21bd76fcfc390100bb86627f43c71",
"sha256": "7f12fb058dd8bfe39545db19eaed57268f5d0f02ec7bcce6a05a428da66834b1"
},
"downloads": -1,
"filename": "os_api_ref-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebc21bd76fcfc390100bb86627f43c71",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 87069,
"upload_time": "2024-11-19T19:39:45",
"upload_time_iso_8601": "2024-11-19T19:39:45.674437Z",
"url": "https://files.pythonhosted.org/packages/9a/1a/ec369a49deb45985237909629dff8594df080b5a40ed52def86c064059a5/os_api_ref-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0070cb40fcbbc647e2f6fa8a1e8ca56d994604832055b0427466a8c65f0b8299",
"md5": "152e49b8bd3257ecbe6b2873d4183cb6",
"sha256": "1900fe54853fb8b07c3bcec50c306a2fc094c9c91ab71ad3720014bd7b8d2107"
},
"downloads": -1,
"filename": "os-api-ref-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "152e49b8bd3257ecbe6b2873d4183cb6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 93116,
"upload_time": "2024-11-19T19:39:47",
"upload_time_iso_8601": "2024-11-19T19:39:47.459595Z",
"url": "https://files.pythonhosted.org/packages/00/70/cb40fcbbc647e2f6fa8a1e8ca56d994604832055b0427466a8c65f0b8299/os-api-ref-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 19:39:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "os-api-ref"
}
JSON