From 61844265d4a6dcd3f256c4389f9a0132c8f2d525 2014-11-24 19:05:30
From: Thomas Kluyver <takowl@gmail.com>
Date: 2014-11-24 19:05:30
Subject: [PATCH] API docs gardening

---

diff --git a/IPython/nbformat/__init__.py b/IPython/nbformat/__init__.py
index 6ad6b9a..d5ba916 100644
--- a/IPython/nbformat/__init__.py
+++ b/IPython/nbformat/__init__.py
@@ -13,6 +13,10 @@ from . import v2
 from . import v3
 from . import v4
 
+__all__ = ['versions', 'validate', 'ValidationError', 'convert', 'from_dict',
+           'NotebookNode', 'current_nbformat', 'current_nbformat_minor',
+           'NBFormatError', 'NO_CONVERT', 'reads', 'read', 'writes', 'write']
+
 versions = {
     1: v1,
     2: v2,
diff --git a/IPython/nbformat/v3/__init__.py b/IPython/nbformat/v3/__init__.py
index 640ce2f..c93834b 100644
--- a/IPython/nbformat/v3/__init__.py
+++ b/IPython/nbformat/v3/__init__.py
@@ -1,20 +1,16 @@
 """The main API for the v3 notebook format.
-
-Authors:
-
-* Brian Granger
 """
 
-#-----------------------------------------------------------------------------
-#  Copyright (C) 2008-2011  The IPython Development Team
-#
-#  Distributed under the terms of the BSD License.  The full license is in
-#  the file COPYING, distributed as part of this software.
-#-----------------------------------------------------------------------------
+# Copyright (c) IPython Development Team.
+# Distributed under the terms of the Modified BSD License.
 
-#-----------------------------------------------------------------------------
-# Imports
-#-----------------------------------------------------------------------------
+__all__ = ['NotebookNode', 'new_code_cell', 'new_text_cell', 'new_notebook',
+           'new_output', 'new_worksheet', 'new_metadata', 'new_author',
+           'new_heading_cell', 'nbformat', 'nbformat_minor', 'nbformat_schema',
+           'reads_json', 'writes_json', 'read_json', 'write_json',
+           'to_notebook_json', 'reads_py', 'writes_py', 'read_py', 'write_py',
+           'to_notebook_py', 'downgrade', 'upgrade', 'parse_filename'
+        ]
 
 import os
 
@@ -35,9 +31,6 @@ from .nbpy import to_notebook as to_notebook_py
 
 from .convert import downgrade, upgrade
 
-#-----------------------------------------------------------------------------
-# Code
-#-----------------------------------------------------------------------------
 
 def parse_filename(fname):
     """Parse a notebook filename.
diff --git a/IPython/nbformat/v4/__init__.py b/IPython/nbformat/v4/__init__.py
index 873134f..03a517e 100644
--- a/IPython/nbformat/v4/__init__.py
+++ b/IPython/nbformat/v4/__init__.py
@@ -3,6 +3,10 @@
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
+__all__ = ['nbformat', 'nbformat_minor', 'nbformat_schema', 'new_code_cell',
+           'new_markdown_cell', 'new_notebook', 'new_output', 'output_from_msg',
+           'reads', 'writes', 'to_notebook', 'downgrade', 'upgrade']
+
 from .nbbase import (
     nbformat, nbformat_minor, nbformat_schema,
     new_code_cell, new_markdown_cell, new_notebook,
diff --git a/docs/autogen_api.py b/docs/autogen_api.py
index b9b084d..e1fc7a6 100755
--- a/docs/autogen_api.py
+++ b/docs/autogen_api.py
@@ -21,8 +21,8 @@ if __name__ == '__main__':
                                         # Extensions are documented elsewhere.
                                         r'\.extensions',
                                         r'\.config\.profile',
-                                        # These should be accessed via nbformat.current
-                                        r'\.nbformat\.v\d+',
+                                        # Old nbformat versions
+                                        r'\.nbformat\.v[1-2]',
                                         # Public API for this is in kernel.zmq.eventloops
                                         r'\.kernel\.zmq\.gui',
                                         # Magics are documented separately
@@ -41,14 +41,21 @@ if __name__ == '__main__':
                                         r'\.core\.magics\.deprecated',
                                         # We document this manually.
                                         r'\.utils\.py3compat',
-                                        # These are exposed by nbformat.current
+                                        # These are exposed by nbformat
                                         r'\.nbformat\.convert',
                                         r'\.nbformat\.validator',
+                                        r'\.nbformat\.notebooknode',
+                                        # Deprecated
+                                        r'\.nbformat\.current',
+                                        # Exposed by nbformat.vN
+                                        r'\.nbformat\.v[3-4]\.nbbase',
                                         # These are exposed in display
                                         r'\.core\.display',
                                         r'\.lib\.display',
                                         # This isn't actually a module
                                         r'\.html\.tasks',
+                                        # This is private
+                                        r'\.html\.allow76'
                                         ]
 
     # These modules import functions and classes from other places to expose
@@ -56,7 +63,9 @@ if __name__ == '__main__':
     # non-API modules they import from should be excluded by the skip patterns
     # above.
     docwriter.names_from__all__.update({
-        'IPython.nbformat.current',
+        'IPython.nbformat',
+        'IPython.nbformat.v3',
+        'IPython.nbformat.v4',
         'IPython.display',
     })