Merge "[contributor] Use code-block for api-guide doc"

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

@@ -47,20 +47,29 @@ 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 locally.::
+#. Clone the api-site repository locally.
 
-    git clone git@github.com:openstack/api-site.git
+   .. code-block:: console
 
-#. Create a Python virtual environment.::
+      $ git clone git@github.com:openstack/api-site.git
 
-    virtualenv wadl2rst
+#. Create a Python virtual environment.
 
-#. Install the requirements and ``wadl2rst`` in the virtual environment.::
+   .. code-block:: console
 
-    pip install -r requirements.txt
-    pip install -e git+git@github.com:annegentle/wadl2rst.git@master#egg=wadl2rst
+      $ virtualenv wadl2rst
 
-#. Create a ``.yaml`` configuration file with the following format.::
+#. Install the requirements and ``wadl2rst`` in the virtual
+   environment.
+
+   .. code-block:: console
+
+      $ pip install -r requirements.txt
+      $ pip install -e git+git@github.com:annegentle/wadl2rst.git@master#egg=wadl2rst
+
+#. Create a ``.yaml`` configuration file with the following format.
+
+   .. code-block:: yaml
 
       [wadl_path]:
           title: [book_title]
@@ -70,12 +79,14 @@ follow these steps.
 This format enables grouping of API operations for more manageable editing
 later.
 
-In the preamble, you can include a header and any introductor text for the
+In the preamble, you can include a header and any introductory text for the
 collected operations.
 
-For example::
+For example:
 
-    ../api-site/api-ref/src/wadls/identity-api/src/v2.0/wadl/identity.wadl:
+.. code-block:: yaml
+
+   /api-site/api-ref/src/wadls/identity-api/src/v2.0/wadl/identity.wadl:
      title: OpenStack Identity API v2.0
      output_file: dist/identity/identity.inc
      preamble: |
@@ -87,9 +98,11 @@ For example::
    OpenStack services REST API.
 
 #. In the wadl2rst directory, run this command with your project's yaml file
-   to run the migration.::
+   to run the migration.
 
-    wadl2rst project.config.yaml
+   .. code-block:: console
+
+      $ wadl2rst project.config.yaml
 
 #. Look at the RST files generated and make sure they contain all the
    operations you expect. Note that the file extension is ``.inc`` to avoid
@@ -98,28 +111,38 @@ For example::
    a toc directive.
 
 #. Next, run the ``fairy-slipper`` tool to generate individual migrated
-   ``<operationid>.yaml`` files. First, clone the repository::
+   ``<operationid>.yaml`` files. First, clone the repository:
 
-    git clone git://git.openstack.org/openstack/fairy-slipper
+   .. code-block:: console
 
-#. Next, get a copy of this patch set::
+      $ git clone git://git.openstack.org/openstack/fairy-slipper
 
-    cd fairy-slipper
-    git review -d 301958
+#. Next, get a copy of this patch set:
+
+   .. code-block:: console
+
+      $ cd fairy-slipper
+      $ git review -d 301958
 
 #. Now, install requirements in the virtual environment.
 
-    pip install -r requirements.txt
+   .. code-block:: console
+
+      $ pip install -r requirements.txt
 
 #. In the ``fairy-slipper`` directory, run the migration script with the
-   ``--create-yamls`` parameter::
+   ``--create-yamls`` parameter:
 
-    ./migrate.sh --create-yamls
+   .. code-block:: console
+
+      $ ./migrate.sh --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::
+   inserts pointers to parameters, such as:
+
+   .. code-block:: none
 
       .. rest_parameters:: parameters.yaml
 
@@ -131,9 +154,11 @@ For example::
 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,
 ``apirefscrape.py``, is in a ``/scripts/`` directory in the wadl2rst
-repository. Run it like so.::
+repository. Run it like so.
 
-    python apirefscrape.py
+.. code-block:: console
+
+   $ python apirefscrape.py
 
 You see output of each service, a count of all operations, and a listing of
 each operation.