From 7cd7df410a8d01dd5c973f8d8273e09aca9b1e2e Mon Sep 17 00:00:00 2001 From: Tim Burke Date: Fri, 26 Aug 2016 13:50:31 -0700 Subject: [PATCH] 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 --- doc/source/service-api.rst | 114 +++++++++++++++++-------------------- 1 file changed, 53 insertions(+), 61 deletions(-) diff --git a/doc/source/service-api.rst b/doc/source/service-api.rst index 02b12d0b..66dd527f 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(, [options])``: Returns stats for the given container. - * ``stat(, , [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(, [options])``: Returns stats for the given container. +* ``stat(, , [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': } -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': } -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': } -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': } -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--objects', where 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--objects', where 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': } -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': } -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