Repository: boto/botocore
Pull request #1112 (2016-12-20 00:06:41)

Add cross links to service API
You'll see that part of the diff is changing the target to `html`.  botocore/boto3 never set the target so it was defaulting to man page.  This meant that for certain style calls in bcdoc, the proper refs/links weren't being generated.

In order to use the new `external_link` method, the target needed to be html.

One option was to only turn on target html when generating html docs, but the `man` target doesn't make much sense for boto3/botocore.

![image](https://cloud.githubusercontent.com/assets/368057/21333496/098e5f1e-c605-11e6-9d18-f4e645f614b0.png)



Patch:
diff --git a/botocore/docs/docstring.py b/botocore/docs/docstring.py
index 5146b79d6..33c68932e 100644
--- a/botocore/docs/docstring.py
+++ b/botocore/docs/docstring.py
@@ -72,7 +72,7 @@ class LazyLoadedDocstring(str):
         return self._docstring
 
     def _create_docstring(self):
-        docstring_structure = DocumentStructure('docstring')
+        docstring_structure = DocumentStructure('docstring', target='html')
         # Call the document method function with the args and kwargs
         # passed to the class.
         self._write_docstring(
diff --git a/botocore/docs/method.py b/botocore/docs/method.py
index c7f0c452c..882c3172e 100644
--- a/botocore/docs/method.py
+++ b/botocore/docs/method.py
@@ -18,6 +18,9 @@ from botocore.docs.example import ResponseExampleDocumenter
 from botocore.docs.example import RequestExampleDocumenter
 
 
+AWS_DOC_BASE = 'https://docs.aws.amazon.com/goto/WebAPI'
+
+
 def get_instance_public_methods(instance):
     """Retrieves an objects public methods
 
@@ -171,6 +174,15 @@ def document_model_driven_method(section, method_name, operation_model,
     # Add the description for the method.
     method_intro_section = section.add_new_section('method-intro')
     method_intro_section.include_doc_string(method_description)
+    service_uid = operation_model.service_model.metadata.get('uid')
+    if service_uid is not None:
+        method_intro_section.style.new_paragraph()
+        method_intro_section.write("See also: ")
+        link = '%s/%s/%s' % (AWS_DOC_BASE, service_uid,
+                             operation_model.name)
+        method_intro_section.style.external_link(title="AWS API Documentation",
+                                                 link=link)
+        method_intro_section.writeln('')
 
     # Add the example section.
     example_section = section.add_new_section('example')
diff --git a/botocore/docs/service.py b/botocore/docs/service.py
index 45968129f..c9b5d7b31 100644
--- a/botocore/docs/service.py
+++ b/botocore/docs/service.py
@@ -41,7 +41,8 @@ class ServiceDocumenter(object):
         :returns: The reStructured text of the documented service.
         """
         doc_structure = DocumentStructure(
-            self._service_name, section_names=self.sections)
+            self._service_name, section_names=self.sections,
+            target='html')
         self.title(doc_structure.get_section('title'))
         self.table_of_contents(doc_structure.get_section('table-of-contents'))
         self.client_api(doc_structure.get_section('client-api'))


Test patch:
diff --git a/tests/unit/docs/__init__.py b/tests/unit/docs/__init__.py
index fb7cd2c76..ef23eeca9 100644
--- a/tests/unit/docs/__init__.py
+++ b/tests/unit/docs/__init__.py
@@ -47,7 +47,7 @@ class BaseDocsTest(unittest.TestCase):
         self.events = HierarchicalEmitter()
         self.setup_client()
         self.doc_name = 'MyDoc'
-        self.doc_structure = DocumentStructure(self.doc_name)
+        self.doc_structure = DocumentStructure(self.doc_name, target='html')
 
     def tearDown(self):
         shutil.rmtree(self.root_dir)
@@ -90,6 +90,7 @@ class BaseDocsTest(unittest.TestCase):
                 'endpointPrefix': 'myservice',
                 'signatureVersion': 'v4',
                 'serviceFullName': 'AWS MyService',
+                'uid': 'myservice-2014-01-01',
                 'protocol': 'query'
             },
             'operations': {
diff --git a/tests/unit/docs/test_method.py b/tests/unit/docs/test_method.py
index 1900d24a2..2be588026 100644
--- a/tests/unit/docs/test_method.py
+++ b/tests/unit/docs/test_method.py
@@ -116,9 +116,15 @@ class TestDocumentModelDrivenMethod(BaseDocsTest):
             method_description='This describes the foo method.',
             example_prefix='response = client.foo'
         )
+        cross_ref_link = (
+            'See also: `AWS API Documentation '
+            '<https://docs.aws.amazon.com/goto/WebAPI'
+            '/myservice-2014-01-01/SampleOperation>'
+        )
         self.assert_contains_lines_in_order([
             '.. py:method:: foo(**kwargs)',
             '  This describes the foo method.',
+            cross_ref_link,
             '  **Request Syntax**',
             '  ::',
             '    response = client.foo(',