Repository: boto/botocore
Pull request #567 (2015-06-17 20:47:47)

Change use of example to syntax in docs
Update headers in methods to be ``Request Syntax`` and ``Response Syntax`` as opposed to ``Request Example`` and ``Response Example``.

cc @jamesls @mtdowling 


Patch:
diff --git a/botocore/docs/method.py b/botocore/docs/method.py
index 43724abbc..d5fdce37b 100644
--- a/botocore/docs/method.py
+++ b/botocore/docs/method.py
@@ -159,7 +159,7 @@ def document_model_driven_method(section, method_name, operation_model,
     # Add the example section.
     example_section = section.add_new_section('example')
     example_section.style.new_paragraph()
-    example_section.style.bold('Example')
+    example_section.style.bold('Request Syntax')
     if operation_model.input_shape:
         RequestExampleDocumenter(
             service_name=operation_model.service_model.service_name,
@@ -196,7 +196,7 @@ def document_model_driven_method(section, method_name, operation_model,
         # Add an example return value
         return_example_section = return_section.add_new_section('example')
         return_example_section.style.new_line()
-        return_example_section.style.bold('Response Example')
+        return_example_section.style.bold('Response Syntax')
         return_example_section.style.new_paragraph()
         ResponseExampleDocumenter(
             service_name=operation_model.service_model.service_name,


Test patch:
diff --git a/tests/unit/docs/test_client.py b/tests/unit/docs/test_client.py
index 5613e3c76..01b07f4b8 100644
--- a/tests/unit/docs/test_client.py
+++ b/tests/unit/docs/test_client.py
@@ -39,7 +39,7 @@ class TestClientDocumenter(BaseDocsTest):
             '  .. py:method:: get_paginator(operation_name)',
             '  .. py:method:: get_waiter(waiter_name)',
             '  .. py:method:: sample_operation(Biz=None)',
-            '    **Example**',
+            '    **Request Syntax**',
             '    ::',
             '      response = client.sample_operation(',
             '          Biz=\'string\'',
@@ -48,7 +48,7 @@ class TestClientDocumenter(BaseDocsTest):
             '    :param Biz:',
             '    :rtype: dict',
             '    :returns:',
-            '      **Response Example**',
+            '      **Response Syntax**',
             '      ::',
             '        {',
             '            \'Biz\': \'string\'',
diff --git a/tests/unit/docs/test_method.py b/tests/unit/docs/test_method.py
index 0d7e10e90..f466f4abe 100644
--- a/tests/unit/docs/test_method.py
+++ b/tests/unit/docs/test_method.py
@@ -97,7 +97,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
         self.assert_contains_lines_in_order([
             '.. py:method:: foo(Bar=None)',
             '  This describes the foo method.',
-            '  **Example**',
+            '  **Request Syntax**',
             '  ::',
             '    response = client.foo(',
             '        Bar=\'string\'',
@@ -106,7 +106,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
             '  :param Bar:',
             '  :rtype: dict',
             '  :returns:',
-            '    **Response Example**',
+            '    **Response Syntax**',
             '    ::',
             '      {',
             '          \'Bar\': \'string\'',
@@ -128,7 +128,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
         self.assert_contains_lines_in_order([
             '.. py:method:: foo()',
             '  This describes the foo method.',
-            '  **Example**',
+            '  **Request Syntax**',
             '  ::',
             '    response = client.foo()',
             '  :returns: None',
@@ -149,7 +149,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
         self.assert_contains_lines_in_order([
             '.. py:method:: foo(Bar=None, Biz=None)',
             '  This describes the foo method.',
-            '  **Example**',
+            '  **Request Syntax**',
             '  ::',
             '    response = client.foo(',
             '        Bar=\'string\',',
@@ -161,7 +161,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
             '  :param Biz: biz docs',
             '  :rtype: dict',
             '  :returns:',
-            '    **Response Example**',
+            '    **Response Syntax**',
             '    ::',
             '      {',
             '          \'Bar\': \'string\'',
@@ -186,7 +186,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
         self.assert_contains_lines_in_order([
             '.. py:method:: foo(Bar=None)',
             '  This describes the foo method.',
-            '  **Example**',
+            '  **Request Syntax**',
             '  ::',
             '    response = client.foo(',
             '        Bar=\'string\'',
@@ -195,7 +195,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
             '  :param Bar:',
             '  :rtype: dict',
             '  :returns:',
-            '    **Response Example**',
+            '    **Response Syntax**',
             '    ::',
             '      {',
             '          \'Bar\': \'string\'',
@@ -219,7 +219,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
         self.assert_contains_lines_in_order([
             '.. py:method:: foo(Biz=None)',
             '  This describes the foo method.',
-            '  **Example**',
+            '  **Request Syntax**',
             '  ::',
             '    response = client.foo(',
             '        Biz=\'string\'',
@@ -228,7 +228,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
             '  :param Biz:',
             '  :rtype: dict',
             '  :returns:',
-            '    **Response Example**',
+            '    **Response Syntax**',
             '    ::',
             '      {',
             '          \'Bar\': \'string\'',
@@ -256,7 +256,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
         self.assert_contains_lines_in_order([
             '.. py:method:: foo(Bar=None, Biz=None)',
             '  This describes the foo method.',
-            '  **Example**',
+            '  **Request Syntax**',
             '  ::',
             '    response = client.foo(',
             '        Bar=\'string\'',
@@ -266,7 +266,7 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
             '  :param Biz:',
             '  :rtype: dict',
             '  :returns:',
-            '    **Response Example**',
+            '    **Response Syntax**',
             '    ::',
             '      {',
             '          \'Biz\': \'string\'',
diff --git a/tests/unit/docs/test_paginator.py b/tests/unit/docs/test_paginator.py
index 73b1e0aef..583418c88 100644
--- a/tests/unit/docs/test_paginator.py
+++ b/tests/unit/docs/test_paginator.py
@@ -42,7 +42,7 @@ class TestPaginatorDocumenter(BaseDocsTest):
             '  .. py:method:: paginate(Biz=None, PaginationConfig=None)',
             ('    Creates an iterator that will paginate through responses'
              ' from :py:meth:`myservice.Client.sample_operation`.'),
-            '    **Example**',
+            '    **Request Syntax**',
             '    ::',
             '      response_iterator = paginator.paginate(',
             '          Biz=\'string\',',
@@ -63,7 +63,7 @@ class TestPaginatorDocumenter(BaseDocsTest):
             '      - **StartingToken** *(string) --*',
             '    :rtype: dict',
             '    :returns:',
-            '      **Response Example**',
+            '      **Response Syntax**',
             '      ::',
             '        {',
             '            \'Biz\': \'string\',',
diff --git a/tests/unit/docs/test_waiter.py b/tests/unit/docs/test_waiter.py
index 4af246219..cf6919c85 100644
--- a/tests/unit/docs/test_waiter.py
+++ b/tests/unit/docs/test_waiter.py
@@ -40,7 +40,7 @@ class TestWaiterDocumenter(BaseDocsTest):
             ('    This polls :py:meth:`myservice.Client.sample_operation` '
              'every 15 seconds until a successful state is reached. An error '
              'is returned after 40 failed checks.'),
-            '    **Example**',
+            '    **Request Syntax**',
             '    ::',
             '      waiter.wait(',
             '          Biz=\'string\'',