Merge "Updates for how the migration tool works for API reference"

Jenkins 7 years ago committed by Gerrit Code Review
commit 9c61cd604f

@ -9,17 +9,18 @@ Source files for
The ``_ web site is intended for application developers
using the OpenStack APIs to build upon. It contains links to multiple SDKs for
specific programming languages, an API reference, and API Guides.
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`` to generate the documents.
``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 However, the HTML output builds for Swagger are not yet
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
@ -43,41 +44,89 @@ 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.
If your project needs to migrate to RST and YAML as nova has done, follow these
When your project needs to migrate to RST (.inc) and YAML as nova has done,
follow these steps.
#. Clone the api-site repository locally.::
git clone
#. Clone the wadl2rst repository locally.::
#. Create a Python virtual environment.::
virtualenv wadl2rst
#. Change directories to the ``wadl2rst`` directory.::
#. Install the requirements and ``wadl2rst`` in the virtual environment.::
cd wadl2rst
pip install -r requirements.txt
pip install -e
#. In the wadl2rst directory, create a configuration YAML file to indicate
which WADL file to migrate as well as the title and destination directory. The
first line provides a relative path to the WADL file. If you have multiple WADL
files, list them all in a single YAML file.::
#. Create a ``.yaml`` configuration file with the following format.::
title: OpenStack Compute API v2.1
output_directory: dist/collected
title: OpenStack Compute API v2.1
output_directory: dist/collected
title: [book_title]
output_file: [output_file]
preamble: [preamble]
#. Save the file as a ``.yaml`` file, such as ``project.config.yaml``.
This format enables grouping of API operations for more manageable editing
#. In the wadl2rst directory, run the script::
In the preamble, you can include a header and any introductor text for the
collected operations.
For example::
title: OpenStack Identity API v2.0
output_file: dist/identity/
preamble: |
Gets an authentication token that permits access to the
OpenStack services REST API.
#. In the wadl2rst directory, run this command with your project's yaml file
to run the migration.::
wadl2rst project.config.yaml
#. Look at the RST files generated and make sure they contain all the
operations you expect.
operations you expect. 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.
#. Next, run the ``fairy-slipper`` tool to generate individual migrated
``<operationid>.yaml`` files. First, clone the repository::
git clone git://
#. Next, get a copy of this patch set::
cd fairy-slipper
git review -d 301958
#. Now, install requirements in the virtual environment.
pip install -r requirements.txt
#. In the ``fairy-slipper`` directory, run the migration script with the
``--create-yamls`` parameter::
./ --create-yamls
The YAML files are placed in an ``api_doc/<service>/<version>`` directory.
The YAML files can be referenced from the RST files, and the migration tool
inserts pointers to parameters, such as::
.. rest_parameters:: parameters.yaml
- name: name
- description: description
- alias: alias
- updated: updated
Optional: 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,
@ -99,7 +148,9 @@ your project teams repository. You can find a suggested outline in the
You need the `extensions`_ for the API reference information.
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
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