docs/autogen_api.py

#!/usr/bin/env python
"""Script to auto-generate our API docs.
"""

import os
import sys

pjoin = os.path.join

here = os.path.abspath(os.path.dirname(__file__))
sys.path.append(pjoin(os.path.abspath(here), 'sphinxext'))

from apigen import ApiDocWriter

source = pjoin(here, 'source')

#*****************************************************************************
if __name__ == '__main__':
    package = 'IPython'
    outdir = pjoin(source, 'api', 'generated')
    docwriter = ApiDocWriter(package,rst_extension='.rst')
    # You have to escape the . here because . is a special char for regexps.
    # You must do make clean if you change this!
    docwriter.package_skip_patterns += [r'\.external$',
                                        # Extensions are documented elsewhere.
                                        r'\.extensions',
                                        # Magics are documented separately
                                        r'\.core\.magics',
                                        # This isn't API
                                        r'\.sphinxext',
                                        # Shims
                                        r'\.kernel',
                                        r'\.terminal\.pt_inputhooks',
                                        ]

    # The inputhook* modules often cause problems on import, such as trying to
    # load incompatible Qt bindings. It's easiest to leave them all out. The
    docwriter.module_skip_patterns += [
        r"\.lib\.inputhook.+",
        r"\.ipdoctest",
        r"\.testing\.plugin",
        # Backwards compat import for lib.lexers
        r"\.nbconvert\.utils\.lexers",
        # We document this manually.
        r"\.utils\.py3compat",
        # These are exposed in display
        r"\.core\.display",
        r"\.lib\.display",
        # Shims
        r"\.config",
        r"\.consoleapp",
        r"\.frontend$",
        r"\.html",
        r"\.nbconvert",
        r"\.nbformat",
        r"\.parallel",
        r"\.qt",
        # this is deprecated.
        r"\.utils\.version",
        # Private APIs (there should be a lot more here)
        r"\.terminal\.ptutils",
    ]
    # main API is in the inputhook module, which is documented.

    # These modules import functions and classes from other places to expose
    # them as part of the public API. They must have __all__ defined. The
    # non-API modules they import from should be excluded by the skip patterns
    # above.
    docwriter.names_from__all__.update(
        {
            "IPython",
            "IPython.display",
        }
    )

    # Now, generate the outputs
    docwriter.write_api_docs(outdir)
    # Write index with .txt extension - we can include it, but Sphinx won't try
    # to compile it
    docwriter.write_index(outdir, 'gen.txt',
                          relative_to = pjoin(source, 'api')
                          )
    print ('%d files written' % len(docwriter.written_modules))