Move Signature to code block, like c++

Change: 149969411

3 files changed, 49 insertions, 14 deletions

diff --git a/tensorflow/tools/docs/parser.py b/tensorflow/tools/docs/parser.py
index a1aad01496..dc65702cc0 100644
--- a/tensorflow/tools/docs/parser.py
+++ b/tensorflow/tools/docs/parser.py
@@ -526,10 +526,10 @@ def _remove_first_line_indent(string):
 
 
 def _generate_signature(func, reverse_index):
-  """Given a function, returns a string representing its args.
+  """Given a function, returns a list of strings representing its args.
 
-  This function produces a string representing the arguments to a python
-  function, including surrounding parentheses. It uses inspect.getargspec, which
+  This function produces a list of strings representing the arguments to a
+  python function. It uses inspect.getargspec, which
   does not generalize well to Python 3.x, which is more flexible in how *args
   and **kwargs are handled. This is not a problem in TF, since we have to remain
   compatible to Python 2.7 anyway.
@@ -545,7 +545,8 @@ def _generate_signature(func, reverse_index):
     reverse_index: A map from object ids to canonical full names to use.
 
   Returns:
-    A string representing the signature of `func` as python code.
+    A list of strings representing the argument signature of `func` as python
+    code.
   """
 
   # This produces poor signatures for decorated functions.
@@ -618,7 +619,7 @@ def _generate_signature(func, reverse_index):
   if argspec.keywords:
     args_list.append('**' + argspec.keywords)
 
-  return '(%s)' % ', '.join(args_list)
+  return args_list
 
 
 def _get_guides_markdown(duplicate_names, guide_index, relative_path):
@@ -693,6 +694,10 @@ class _FunctionPageInfo(object):
     return self._full_name
 
   @property
+  def short_name(self):
+    return self._full_name.split('.')[-1]
+
+  @property
   def defined_in(self):
     return self._defined_in
 
@@ -769,6 +774,10 @@ class _ClassPageInfo(object):
     return self._full_name
 
   @property
+  def short_name(self):
+    return self._full_name.split('.')[-1]
+
+  @property
   def defined_in(self):
     return self._defined_in
 
@@ -950,6 +959,10 @@ class _ModulePageInfo(object):
     return self._full_name
 
   @property
+  def short_name(self):
+    return self._full_name.split('.')[-1]
+
+  @property
   def defined_in(self):
     return self._defined_in
 
@@ -1271,6 +1284,7 @@ def _get_defined_in(py_object, parser_config):
     return _PythonFile(path, parser_config)
 
 
+# TODO(markdaoust): This should just parse, pretty_docs should generate the md.
 def generate_global_index(library_name, index, reference_resolver):
   """Given a dict of full names to python objects, generate an index page.
 
diff --git a/tensorflow/tools/docs/parser_test.py b/tensorflow/tools/docs/parser_test.py
index a8f466b251..abfa1cf529 100644
--- a/tensorflow/tools/docs/parser_test.py
+++ b/tensorflow/tools/docs/parser_test.py
@@ -136,7 +136,7 @@ class ParserTest(googletest.TestCase):
     self.assertEqual(TestClass.a_method, page_info.methods[0].obj)
 
     # Make sure that the signature is extracted properly and omits self.
-    self.assertEqual('(arg=\'default\')', page_info.methods[0].signature)
+    self.assertEqual(["arg='default'"], page_info.methods[0].signature)
 
     # Make sure the property is present
     self.assertIs(TestClass.a_property, page_info.properties[0].obj)
@@ -208,7 +208,7 @@ class ParserTest(googletest.TestCase):
         inspect.getdoc(test_function).split('\n')[0], page_info.doc.brief)
 
     # Make sure the extracted signature is good.
-    self.assertEqual('(unused_arg, unused_kwarg=\'default\')',
+    self.assertEqual(['unused_arg', "unused_kwarg='default'"],
                      page_info.signature)
 
     # Make sure this file is contained as the definition location.
@@ -239,7 +239,7 @@ class ParserTest(googletest.TestCase):
         page_info.doc.brief)
 
     # Make sure the extracted signature is good.
-    self.assertEqual('(unused_arg, *unused_args, **unused_kwargs)',
+    self.assertEqual(['unused_arg', '*unused_args', '**unused_kwargs'],
                      page_info.signature)
 
   def test_parse_md_docstring(self):
diff --git a/tensorflow/tools/docs/pretty_docs.py b/tensorflow/tools/docs/pretty_docs.py
index 7d7827b7f5..029e46438f 100644
--- a/tensorflow/tools/docs/pretty_docs.py
+++ b/tensorflow/tools/docs/pretty_docs.py
@@ -48,16 +48,16 @@ def build_md_page(page_info):
 
 def _build_function_page(page_info):
   """Given a FunctionPageInfo object Return the page as an md string."""
-  parts = [
-      '# {page_info.full_name}{page_info.signature}\n\n'.format(
-          page_info=page_info)
-  ]
+  parts = ['# %s\n\n' % page_info.full_name]
 
   if page_info.aliases:
-    parts.extend('### `%s%s`\n' % (name, page_info.signature)
+    parts.extend('### `%s`\n' % name
                  for name in page_info.aliases)
     parts.append('\n')
 
+  if page_info.signature is not None:
+    parts.append(_build_signature(page_info))
+
   if page_info.defined_in:
     parts.append('\n\n')
     parts.append(str(page_info.defined_in))
@@ -123,10 +123,13 @@ def _build_class_page(page_info):
 
     for method_info in sorted(inits) + sorted(others):
       h3 = ('<h3 id="{short_name}">'
-            '<code>{short_name}{signature}</code>'
+            '<code>{short_name}</code>'
             '</h3>\n\n')
       parts.append(h3.format(**method_info.__dict__))
 
+      if method_info.signature is not None:
+        parts.append(_build_signature(method_info))
+
       parts.append(method_info.doc.docstring)
       parts.append(_build_function_details(method_info.doc.function_details))
       parts.append(_build_compatibility(method_info.doc.compatibility))
@@ -193,6 +196,24 @@ def _build_module_page(page_info):
   return ''.join(parts)
 
 
+def _build_signature(obj_info):
+  """Returns a md code block showing the function signature."""
+  signature_template = '\n'.join([
+      '``` python',
+      '{name}({sig})',
+      '```\n\n'])
+
+  if not obj_info.signature:
+    sig = ''
+  elif len(obj_info.signature) == 1:
+    sig = obj_info.signature[0]
+  else:
+    sig = ',\n'.join('    %s' % sig_item for sig_item in obj_info.signature)
+    sig = '\n'+sig+'\n'
+
+  return signature_template.format(name=obj_info.short_name, sig=sig)
+
+
 def _build_compatibility(compatibility):
   """Return the compatability section as an md string."""
   parts = []