Updates Contributor Guide for API docs now that WADL migration is complete

Change-Id: Ibc05df66a8aabdb51fa7b98210a55eab027ebeee

doc/contributor-guide/source/api-guides.rst

@@ -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
+files. The RST and YAML files get stored in your project repository in an
-the RST and YAML files in your project repository in an ``api-ref`` directory.
+``api-ref`` directory. The nova project has an example you can follow,
-The nova project has an example you can follow, including tox jobs for running
+including tox jobs for running ``tox -e api-ref`` within the ``api-ref``
-``tox -e api`` within the ``wadl2rst`` directory to generate the documents.
+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.
 
 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
+Use these instructions if you have no documentation currently, or want to
-RST files for the content and YAML files for the parameters. See
+update it to match OpenStack standards.
-: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.
 
 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
+      rm -rf api-ref/build
-        sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+      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
+If your document is completely new, you need to add links to it from the API
-``api-guide`` folder in the nova repository. Other projects can mimic these
+landing page and the OpenStack Governance reference document, projects.yaml.
-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.
+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