Updates Contributor Guide for API docs now that WADL migration is complete
Change-Id: Ibc05df66a8aabdb51fa7b98210a55eab027ebeee
This commit is contained in:
Anne Gentle
parent
2a38e25e7a
commit
33891a7f98
@ -12,15 +12,10 @@ using the OpenStack APIs to build upon. It contains links to multiple SDKs for
|
||||
specific programming languages, API references, and API Guides.
|
||||
|
||||
For existing APIs, the reference information comes from RST and YAML source
|
||||
files. To convert from WADL to RST, use a tool called `wadl2rst`_. Then store
|
||||
the RST and YAML files in your project repository in an ``api-ref`` directory.
|
||||
The nova project has an example you can follow, including tox jobs for running
|
||||
``tox -e api`` within the ``wadl2rst`` directory to generate the documents.
|
||||
|
||||
Alternatively, a project can describe their API with Swagger or OpenAPI. To
|
||||
learn more about the Swagger format and OpenAPI initiative, refer to
|
||||
https://swagger.io. However, the HTML output builds for Swagger are not yet
|
||||
created.
|
||||
files. The RST and YAML files get stored in your project repository in an
|
||||
``api-ref`` directory. The nova project has an example you can follow,
|
||||
including tox jobs for running ``tox -e api-ref`` within the ``api-ref``
|
||||
directory to generate the documents.
|
||||
|
||||
The RST conceptual and how-to files are stored in each project's
|
||||
``doc/source/api-guide`` directory. These are built to locations based on the
|
||||
@ -35,7 +30,16 @@ Standards for API reference in OpenStack
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The API working group has `API documentation guidelines`_ that all teams
|
||||
providing a REST API service in OpenStack strive to follow.
|
||||
providing a REST API service in OpenStack strive to follow. This
|
||||
document tells you what and how much to write. If you follow the suggested
|
||||
outline, your API guide will be accurate and complete.
|
||||
|
||||
If your project does not have any documentation, you can find a suggested
|
||||
outline in the `API documentation guidelines`_. The Compute project has
|
||||
examples to follow:
|
||||
|
||||
* http://git.openstack.org/cgit/openstack/nova/tree/api-guide
|
||||
* http://git.openstack.org/cgit/openstack/nova/tree/api-ref
|
||||
|
||||
For service names, you must adhere to the official name for the service as
|
||||
indicated in the governance repository in the ``reference/projects.yaml``
|
||||
@ -49,18 +53,30 @@ please ask your PTL or a Technical Committee member how to proceed.
|
||||
How to document your OpenStack API service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you have a WADL file, we recommend using the migration process to create
|
||||
RST files for the content and YAML files for the parameters. See
|
||||
:ref:`how-to-migrate-wadl`.
|
||||
|
||||
If you have no documentation currently, or want to
|
||||
update it to be consistent with other projects, read more here.
|
||||
Use these instructions if you have no documentation currently, or want to
|
||||
update it to match OpenStack standards.
|
||||
|
||||
The basic steps are:
|
||||
|
||||
#. Create an ``api-ref/source`` directory in your project repository.
|
||||
|
||||
#. Create a ``conf.py`` for the project, similar to the `nova example`_.
|
||||
#. Create a ``conf.py`` for the project, similar to the `nova example`_. In it,
|
||||
include the html theme, openstackdocstheme, use the os-api-ref Sphinx
|
||||
extension, and also point the bug reporting link to your project's repo::
|
||||
|
||||
import openstackdocstheme
|
||||
|
||||
extensions = [
|
||||
'os_api_ref',
|
||||
]
|
||||
|
||||
|
||||
html_theme = 'openstackdocs'
|
||||
html_theme_path = [openstackdocstheme.get_html_theme_path()]
|
||||
html_theme_options = {
|
||||
"sidebar_mode": "toc",
|
||||
}
|
||||
html_context = {'bug_project': 'nova', 'bug_tag': 'api-ref'}
|
||||
|
||||
#. Update the ``test-requirements.txt`` file for the project with a line for
|
||||
the ``os-api-ref`` Sphinx extension::
|
||||
@ -103,17 +119,9 @@ The basic steps are:
|
||||
[testenv:api-ref]
|
||||
# This environment is called from CI scripts to test and publish
|
||||
# the API Ref to developer.openstack.org.
|
||||
# NOTE(sdague): this target does not use constraints because
|
||||
# upstream infra does not yet support it. Once that's fixed, we can
|
||||
# drop the install_command.
|
||||
#
|
||||
# we do not used -W here because we are doing some slightly tricky
|
||||
# things to build a single page document, and as such, we are ok
|
||||
# ignoring the duplicate stanzas warning.
|
||||
install_command = pip install -U --force-reinstall {opts} {packages}
|
||||
commands =
|
||||
rm -rf api-ref/build
|
||||
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
|
||||
rm -rf api-ref/build
|
||||
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
|
||||
|
||||
#. Test the ``tox.ini`` changes by running this tox command:
|
||||
|
||||
@ -125,149 +133,20 @@ The basic steps are:
|
||||
https://review.openstack.org/#/c/305464/ and
|
||||
https://review.openstack.org/#/c/305485/.
|
||||
|
||||
.. _how-to-migrate-wadl:
|
||||
|
||||
How to migrate WADL files for your OpenStack API service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If your project already has WADL files, they are migrated to Swagger files with
|
||||
every commit to the api-site repository. However, some APIs cannot be described
|
||||
with Swagger.
|
||||
|
||||
When your project needs to migrate to RST (.inc) and YAML as nova has done,
|
||||
follow these steps.
|
||||
|
||||
#. Clone the api-site repository:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git clone https://github.com/openstack/api-site
|
||||
|
||||
The files are available in api-ref/source/<service>/<version>/.
|
||||
|
||||
#. Look at the RST files generated and make sure they contain all the
|
||||
operations you expect. The ``.inc`` files contain groupings of the
|
||||
operations.
|
||||
|
||||
.. note::
|
||||
|
||||
Note that the file extension is ``.inc`` to avoid
|
||||
build errors. When included files are ``.inc`` files, Sphinx does not
|
||||
issue warnings about generating the documents twice, or documents not
|
||||
being in a toc directive.
|
||||
|
||||
#. In addition to separate files for each operation's parameters, there is a
|
||||
``parameters.yaml`` file for your service. Check the accuracy of these
|
||||
files.
|
||||
|
||||
The YAML files can be referenced from the RST files, you can place pointers
|
||||
to parameters, such as:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- name: name
|
||||
- description: description
|
||||
- alias: alias
|
||||
- updated: updated
|
||||
|
||||
#. Copy the files to your project's repository.
|
||||
|
||||
#. Refer to :ref:`how-to-document-api` for details on how to build and publish
|
||||
the files.
|
||||
|
||||
Optional: Determine how many operations are currently documented
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can run a screen scraper program if you want to get a count of
|
||||
your project's total number of operations. The Python script,
|
||||
``apirefscrape.py``, is in a ``/scripts/`` directory in the wadl2rst
|
||||
repository.
|
||||
|
||||
#. To run the counting tool, clone a copy of the wadl2rst repository:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git clone https://github.com/annegentle/wadl2rst
|
||||
|
||||
#. Change directories to ``wadl2rst`` and then create a python virtualenv:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd wadl2rst
|
||||
$ virtualenv wadl2rst
|
||||
|
||||
#. Install Python requests and lxml:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install requests
|
||||
$ pip install lxml
|
||||
|
||||
#. Run the script.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ python scripts/apirefscrape.py
|
||||
URL: api-ref-telemetry-v2.html
|
||||
----------
|
||||
19
|
||||
19
|
||||
GET /v2/alarms
|
||||
POST /v2/alarms
|
||||
GET /v2/alarms/{alarm_id}
|
||||
PUT /v2/alarms/{alarm_id}
|
||||
DELETE /v2/alarms/{alarm_id}
|
||||
PUT /v2/alarms/{alarm_id}/state
|
||||
GET /v2/alarms/{alarm_id}/state
|
||||
GET /v2/alarms/{alarm_id}/history
|
||||
GET /v2/meters
|
||||
POST /v2/meters/{meter_name}
|
||||
GET /v2/meters/{meter_name}
|
||||
GET /v2/meters/{meter_name}/statistics
|
||||
GET /v2/samples
|
||||
GET /v2/samples/{sample_id}
|
||||
GET /v2/resources
|
||||
GET /v2/resources/{resource_id}
|
||||
GET /v2/capabilities
|
||||
GET /v2/events
|
||||
GET /v2/events/{message_id}
|
||||
|
||||
You see output of each service, a count of all operations, and a listing of
|
||||
each operation.
|
||||
|
||||
If your project does not have any documentation, then you may write Swagger
|
||||
plus RST to document your API calls, parameters, and reference information. You
|
||||
can generate Swagger from annotations or create Swagger from scratch. You
|
||||
should review, store, and build RST for conceptual or how-to information from
|
||||
your project team’s repository. You can find a suggested outline in the
|
||||
`API documentation guidelines`_. The Compute project has examples to follow:
|
||||
|
||||
* http://git.openstack.org/cgit/openstack/nova/tree/api-guide
|
||||
* http://git.openstack.org/cgit/openstack/nova/tree/api-ref
|
||||
|
||||
You need the `extensions`_ for the API reference information. Those will be
|
||||
centralized in milestone 2, but for now you need to copy the directory to use
|
||||
those.
|
||||
|
||||
All projects should use this set of `API documentation guidelines`_ from the
|
||||
OpenStack API working group any time their service has a REST API. This
|
||||
document tells you what and how much to write. If you follow the suggested
|
||||
outline, your API guide will be accurate and complete.
|
||||
|
||||
After the source files and build jobs exist, the docs are built to
|
||||
`developer.openstack.org`_.
|
||||
|
||||
For the nova project, place your how-to and conceptual articles in the
|
||||
``api-guide`` folder in the nova repository. Other projects can mimic these
|
||||
patches that created an api-guide and build jobs for the Compute api-guide. You
|
||||
should also set up reference information in your project repo.
|
||||
If your document is completely new, you need to add links to it from the API
|
||||
landing page and the OpenStack Governance reference document, projects.yaml.
|
||||
|
||||
To add a link to the project's API docs to the API landing page, patch the
|
||||
``index.rst`` file stored in the `openstack/api-site repository`_.
|
||||
|
||||
To ensure the openstack/governance repository has the correct link to your API
|
||||
documentation, patch the ``reference/projects.yaml`` file in the
|
||||
`openstack/governance repository`.
|
||||
|
||||
|
||||
You can embed annotations in your source code if you want to generate the
|
||||
reference information. Here’s an `example patch`_ from the nova project.
|
||||
Because we haven’t had a project do this yet completely, the build jobs still
|
||||
need to be written.
|
||||
|
||||
.. _`developer.openstack.org`: http://developer.openstack.org
|
||||
.. _`wadl2rst`: http://github.com/annegentle/wadl2rst
|
||||
@ -275,4 +154,5 @@ need to be written.
|
||||
.. _`example patch`: https://review.openstack.org/#/c/233446/
|
||||
.. _`API documentation guidelines`: http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html
|
||||
.. _`nova example`: https://github.com/openstack/nova/blob/master/api-ref/source/conf.py
|
||||
.. _`extensions`: http://git.openstack.org/cgit/openstack/nova/tree/api-ref/ext
|
||||
.. _`openstack/api-site repository`: http://git.openstack.org/cgit/openstack/api-site/tree/api-quick-start/source/index.rst
|
||||
.. _`openstack/governance repository`: http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml
|
||||
|
||||
Loading…
Reference in New Issue
Block a user