Fix docs autogen script.

docs/autogen.py

@@ -406,31 +406,70 @@ def code_snippet(snippet):
     return result
 
 
-def process_class_docstring(docstring):
+def count_leading_spaces(s):
+    ws = re.search('\S', s)
+    if ws:
+        return ws.start()
+    else:
+        return 0
+
+
+def process_docstring(docstring):
+    # First, extract code blocks and process them.
+    code_blocks = []
+    if '```' in docstring:
+        tmp = docstring[:]
+        while '```' in tmp:
+            tmp = tmp[tmp.find('```'):]
+            index = tmp[3:].find('```') + 6
+            snippet = tmp[:index]
+            # Place marker in docstring for later reinjection.
+            docstring = docstring.replace(
+                snippet, '$CODE_BLOCK_%d' % len(code_blocks))
+            snippet_lines = snippet.split('\n')
+            # Remove leading spaces.
+            num_leading_spaces = snippet_lines[-1].find('`')
+            snippet_lines = ([snippet_lines[0]] +
+                             [line[num_leading_spaces:]
+                             for line in snippet_lines[1:]])
+            # Most code snippets have 3 or 4 more leading spaces
+            # on inner lines, but not all. Remove them.
+            inner_lines = snippet_lines[1:-1]
+            leading_spaces = None
+            for line in inner_lines:
+                if not line or line[0] == '\n':
+                    continue
+                spaces = count_leading_spaces(line)
+                if leading_spaces is None:
+                    leading_spaces = spaces
+                if spaces < leading_spaces:
+                    leading_spaces = spaces
+            if leading_spaces:
+                snippet_lines = ([snippet_lines[0]] +
+                                 [line[leading_spaces:]
+                                  for line in snippet_lines[1:-1]] +
+                                 [snippet_lines[-1]])
+            snippet = '\n'.join(snippet_lines)
+            code_blocks.append(snippet)
+            tmp = tmp[index:]
+
+    # Format docstring section titles.
     docstring = re.sub(r'\n(\s+)# (.*)\n',
                        r'\n\1__\2__\n\n',
                        docstring)
+    # Format docstring lists.
     docstring = re.sub(r'    ([^\s\\\(]+):(.*)\n',
                        r'    - __\1__:\2\n',
                        docstring)
 
-    docstring = docstring.replace('    ' * 5, '\t\t')
-    docstring = docstring.replace('    ' * 3, '\t')
-    docstring = docstring.replace('    ', '')
-    return docstring
-
-
-def process_function_docstring(docstring):
-    docstring = re.sub(r'\n(\s+)# (.*)\n',
-                       r'\n\1__\2__\n\n',
-                       docstring)
-    docstring = re.sub(r'    ([^\s\\\(]+):(.*)\n',
-                       r'    - __\1__:\2\n',
-                       docstring)
+    # Strip all leading spaces.
+    lines = docstring.split('\n')
+    docstring = '\n'.join([line.lstrip(' ') for line in lines])
 
-    docstring = docstring.replace('    ' * 6, '\t\t')
-    docstring = docstring.replace('    ' * 4, '\t')
-    docstring = docstring.replace('    ', '')
+    # Reinject code blocks.
+    for i, code_block in enumerate(code_blocks):
+        docstring = docstring.replace(
+            '$CODE_BLOCK_%d' % i, code_block)
     return docstring
 
 print('Cleaning up existing sources directory.')
@@ -483,7 +522,7 @@ def process_function_docstring(docstring):
         subblocks.append(code_snippet(signature))
         docstring = cls.__doc__
         if docstring:
-            subblocks.append(process_class_docstring(docstring))
+            subblocks.append(process_docstring(docstring))
         blocks.append('\n'.join(subblocks))
 
     functions = page_data.get('functions', [])
@@ -509,7 +548,7 @@ def process_function_docstring(docstring):
         subblocks.append(code_snippet(signature))
         docstring = function.__doc__
         if docstring:
-            subblocks.append(process_function_docstring(docstring))
+            subblocks.append(process_docstring(docstring))
         blocks.append('\n\n'.join(subblocks))
 
     if not blocks:

keras/utils/generic_utils.py

@@ -24,7 +24,7 @@ class CustomObjectScope(object):
 
     # Example
 
-    Consider a custom object `MyObject`
+    Consider a custom object `MyObject` (e.g. a class):
 
     ```python
         with CustomObjectScope({'MyObject':MyObject}):