Fix decorator_utils.add_notice_to_docstring's way of dealing with indented docstrings.

This makes it take into account any indentation that the docstring might contain
internally, and should fix the way docs are eventually converted to Markdown and rendered to HTML.

For example, the docs for tf.contrib.losses.sparse_softmax_cross_entropy [1] are
currently badly rendered , with the args list left unformatted. This CL should fix that.
Also note that the existing deprecation_test.py was actually enforcing the broken
behavior until now.

[1] https://www.tensorflow.org/versions/r0.12/api_docs/python/contrib.losses.html#sparse_softmax_cross_entropy
Change: 140912534

1 files changed, 44 insertions, 1 deletions

diff --git a/tensorflow/python/util/decorator_utils.py b/tensorflow/python/util/decorator_utils.py
index c4b033d59a..df259c7f7c 100644
--- a/tensorflow/python/util/decorator_utils.py
+++ b/tensorflow/python/util/decorator_utils.py
@@ -18,6 +18,8 @@ from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
 
+import sys
+
 
 def get_qualified_name(function):
   # Python 3
@@ -30,13 +32,54 @@ def get_qualified_name(function):
   return function.__name__
 
 
+def _normalize_docstring(docstring):
+  """Normalizes the docstring.
+
+  Replaces tabs with spaces, removes leading and trailing blanks lines, and
+  removes any indentation.
+
+  Copied from PEP-257:
+  https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
+
+  Args:
+    docstring: the docstring to normalize
+
+  Returns:
+    The normalized docstring
+  """
+  if not docstring:
+    return ''
+  # Convert tabs to spaces (following the normal Python rules)
+  # and split into a list of lines:
+  lines = docstring.expandtabs().splitlines()
+  # Determine minimum indentation (first line doesn't count):
+  # (we use sys.maxsize because sys.maxint doesn't exist in Python 3)
+  indent = sys.maxsize
+  for line in lines[1:]:
+    stripped = line.lstrip()
+    if stripped:
+      indent = min(indent, len(line) - len(stripped))
+  # Remove indentation (first line is special):
+  trimmed = [lines[0].strip()]
+  if indent < sys.maxsize:
+    for line in lines[1:]:
+      trimmed.append(line[indent:].rstrip())
+  # Strip off trailing and leading blank lines:
+  while trimmed and not trimmed[-1]:
+    trimmed.pop()
+  while trimmed and not trimmed[0]:
+    trimmed.pop(0)
+  # Return a single string:
+  return '\n'.join(trimmed)
+
+
 def add_notice_to_docstring(
     doc, instructions, no_doc_str, suffix_str, notice):
   """Adds a deprecation notice to a docstring."""
   if not doc:
     lines = [no_doc_str]
   else:
-    lines = doc.splitlines()
+    lines = _normalize_docstring(doc).splitlines()
     lines[0] += ' ' + suffix_str
 
   notice = [''] + notice + [instructions]