Change Examples from headings to topics

Previously, they appeared in the table of contents, which seemed unnecessary.

Additionally, de-dent the bullet list for stat since it looked weird.

Change-Id: Ief5d480beb4a7daa2fd87c27019601332f087602

1 files changed, 53 insertions, 61 deletions

diff --git a/doc/source/service-api.rst b/doc/source/service-api.rst
index 02b12d0..66dd527 100644
--- a/doc/source/service-api.rst
+++ b/doc/source/service-api.rst
@@ -312,11 +312,11 @@ method docstring.
 
 Valid calls for this method are as follows:
 
- * ``stat([options])``: Returns stats for the configured account.
- * ``stat(<container>, [options])``: Returns stats for the given container.
- * ``stat(<container>, <object_list>, [options])``: Returns stats for each
-   of the given objects in the the given container (through the returned
-   iterator).
+* ``stat([options])``: Returns stats for the configured account.
+* ``stat(<container>, [options])``: Returns stats for the given container.
+* ``stat(<container>, <object_list>, [options])``: Returns stats for each
+  of the given objects in the the given container (through the returned
+  iterator).
 
 Results from stat are dictionaries indicating the success or failure of each
 operation. In the case of a successful stat against an account or container,
@@ -371,15 +371,14 @@ operation was not successful, and will include the keys below:
         'error_timestamp': <timestamp>
     }
 
-Example
-^^^^^^^
+.. topic:: Example
 
-The code below demonstrates the use of ``stat`` to retrieve the headers for a
-given list of objects in a container using 20 threads. The code creates a
-mapping from object name to headers which is then pretty printed to the log.
+   The code below demonstrates the use of ``stat`` to retrieve the headers for
+   a given list of objects in a container using 20 threads. The code creates a
+   mapping from object name to headers which is then pretty printed to the log.
 
-.. literalinclude:: ../../examples/stat.py
-   :language: python
+   .. literalinclude:: ../../examples/stat.py
+      :language: python
 
 List
 ~~~~
@@ -438,14 +437,13 @@ dictionary as described below:
         'error_timestamp': <timestamp>
     }
 
-Example
-^^^^^^^
+.. topic:: Example
 
-The code below demonstrates the use of ``list`` to list all items in a
-container that are over 10MiB in size:
+   The code below demonstrates the use of ``list`` to list all items in a
+   container that are over 10MiB in size:
 
-.. literalinclude:: ../../examples/list.py
-   :language: python
+   .. literalinclude:: ../../examples/list.py
+      :language: python
 
 Post
 ~~~~
@@ -484,14 +482,13 @@ described below:
     that each time user metadata is updated, the complete set of desired
     key-value pairs must be specified.
 
-Example
-^^^^^^^
+.. topic:: Example
 
-The code below demonstrates the use of ``post`` to set an archive folder in a
-given container to expire after a 24 hour delay:
+   The code below demonstrates the use of ``post`` to set an archive folder in
+   a given container to expire after a 24 hour delay:
 
-.. literalinclude:: ../../examples/post.py
-   :language: python
+   .. literalinclude:: ../../examples/post.py
+      :language: python
 
 Download
 ~~~~~~~~
@@ -552,14 +549,13 @@ below:
         'response_dict': <HTTP response details>
     }
 
-Example
-^^^^^^^
+.. topic:: Example
 
-The code below demonstrates the use of ``download`` to download all PNG images
-from a dated archive folder in a given container:
+   The code below demonstrates the use of ``download`` to download all PNG
+   images from a dated archive folder in a given container:
 
-.. literalinclude:: ../../examples/download.py
-   :language: python
+   .. literalinclude:: ../../examples/download.py
+      :language: python
 
 Upload
 ~~~~~~
@@ -646,16 +642,15 @@ below:
         'attempts': <attempt count>
     }
 
-Example
-^^^^^^^
+.. topic:: Example
 
-The code below demonstrates the use of ``upload`` to upload all files and
-folders in a given directory, and rename each object by replacing the root
-directory name with 'my-<d>-objects', where <d> is the name of the uploaded
-directory:
+   The code below demonstrates the use of ``upload`` to upload all files and
+   folders in a given directory, and rename each object by replacing the root
+   directory name with 'my-<d>-objects', where <d> is the name of the uploaded
+   directory:
 
-.. literalinclude:: ../../examples/upload.py
-   :language: python
+   .. literalinclude:: ../../examples/upload.py
+      :language: python
 
 Delete
 ~~~~~~
@@ -744,17 +739,16 @@ below:
         'response_dict': <HTTP response details>
     }
 
-Example
-^^^^^^^
+.. topic:: Example
 
-The code below demonstrates the use of ``delete`` to remove a given list of
-objects from a specified container. As the objects are deleted the transaction
-ID of the relevant request is printed along with the object name and number
-of attempts required. By printing the transaction ID, the printed operations
-can be easily linked to events in the swift server logs:
+   The code below demonstrates the use of ``delete`` to remove a given list of
+   objects from a specified container. As the objects are deleted the
+   transaction ID of the relevant request is printed along with the object name
+   and number of attempts required. By printing the transaction ID, the printed
+   operations can be easily linked to events in the swift server logs:
 
-.. literalinclude:: ../../examples/delete.py
-   :language: python
+   .. literalinclude:: ../../examples/delete.py
+      :language: python
 
 Copy
 ~~~~
@@ -810,14 +804,13 @@ below:
        'error_timestamp': <timestamp>
    }
 
-Example
--------
+.. topic:: Example
 
-The code below demonstrates the use of ``copy`` to add new user metadata for
-objects a and b, and to copy object c to d (with added metadata).
+   The code below demonstrates the use of ``copy`` to add new user metadata for
+   objects a and b, and to copy object c to d (with added metadata).
 
-.. literalinclude:: ../../examples/copy.py
-   :language: python
+   .. literalinclude:: ../../examples/copy.py
+      :language: python
 
 Capabilities
 ~~~~~~~~~~~~
@@ -894,13 +887,12 @@ dictionary is given below:
         }
     }
 
-Example
-^^^^^^^
+.. topic:: Example
 
-The code below demonstrates the use of ``capabilities`` to determine if the
-Swift cluster supports static large objects, and if so, the maximum number of
-segments that can be described in a single manifest file, along with the
-size restrictions on those objects:
+   The code below demonstrates the use of ``capabilities`` to determine if the
+   Swift cluster supports static large objects, and if so, the maximum number
+   of segments that can be described in a single manifest file, along with the
+   size restrictions on those objects:
 
-.. literalinclude:: ../../examples/capabilities.py
-   :language: python
+   .. literalinclude:: ../../examples/capabilities.py
+      :language: python