autogen_api.py
79 lines
| 3.8 KiB
| text/x-python
|
PythonLexer
/ docs / autogen_api.py
Fernando Perez
|
r1850 | #!/usr/bin/env python | ||
"""Script to auto-generate our API docs. | ||||
""" | ||||
# stdlib imports | ||||
import os | ||||
import sys | ||||
# local imports | ||||
sys.path.append(os.path.abspath('sphinxext')) | ||||
from apigen import ApiDocWriter | ||||
#***************************************************************************** | ||||
if __name__ == '__main__': | ||||
pjoin = os.path.join | ||||
package = 'IPython' | ||||
outdir = pjoin('source','api','generated') | ||||
Paul Ivanov
|
r11730 | docwriter = ApiDocWriter(package,rst_extension='.rst') | ||
Brian Granger
|
r2275 | # You have to escape the . here because . is a special char for regexps. | ||
# You must do make clean if you change this! | ||||
Thomas Kluyver
|
r13586 | docwriter.package_skip_patterns += [r'\.external$', | ||
# Extensions are documented elsewhere. | ||||
Brian Granger
|
r2064 | r'\.extensions', | ||
Brian Granger
|
r2275 | r'\.config\.profile', | ||
Thomas Kluyver
|
r19043 | # Old nbformat versions | ||
r'\.nbformat\.v[1-2]', | ||||
Thomas Kluyver
|
r17397 | # Public API for this is in kernel.zmq.eventloops | ||
r'\.kernel\.zmq\.gui', | ||||
Thomas Kluyver
|
r18299 | # Magics are documented separately | ||
r'\.core\.magics', | ||||
Fernando Perez
|
r1850 | ] | ||
Fernando Perez
|
r2404 | |||
Thomas Kluyver
|
r13586 | # 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 | ||||
# main API is in the inputhook module, which is documented. | ||||
docwriter.module_skip_patterns += [ r'\.lib\.inputhook.+', | ||||
Fernando Perez
|
r1850 | r'\.ipdoctest', | ||
Thomas Kluyver
|
r13592 | r'\.testing\.plugin', | ||
Thomas Kluyver
|
r13586 | # This just prints a deprecation msg: | ||
Thomas Kluyver
|
r13886 | r'\.frontend$', | ||
Thomas Kluyver
|
r17123 | # Deprecated: | ||
Thomas Kluyver
|
r17300 | r'\.core\.magics\.deprecated', | ||
Thomas Kluyver
|
r14087 | # We document this manually. | ||
r'\.utils\.py3compat', | ||||
Thomas Kluyver
|
r19043 | # These are exposed by nbformat | ||
Thomas Kluyver
|
r17120 | r'\.nbformat\.convert', | ||
r'\.nbformat\.validator', | ||||
Thomas Kluyver
|
r19043 | r'\.nbformat\.notebooknode', | ||
# Deprecated | ||||
r'\.nbformat\.current', | ||||
# Exposed by nbformat.vN | ||||
r'\.nbformat\.v[3-4]\.nbbase', | ||||
Thomas Kluyver
|
r17121 | # These are exposed in display | ||
r'\.core\.display', | ||||
r'\.lib\.display', | ||||
Thomas Kluyver
|
r17301 | # This isn't actually a module | ||
MinRK
|
r18351 | r'\.html\.tasks', | ||
Thomas Kluyver
|
r19043 | # This is private | ||
r'\.html\.allow76' | ||||
Fernando Perez
|
r1850 | ] | ||
Thomas Kluyver
|
r17120 | |||
# 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({ | ||||
Thomas Kluyver
|
r19043 | 'IPython.nbformat', | ||
'IPython.nbformat.v3', | ||||
'IPython.nbformat.v4', | ||||
Thomas Kluyver
|
r17121 | 'IPython.display', | ||
Thomas Kluyver
|
r17120 | }) | ||
Fernando Perez
|
r2568 | |||
# Now, generate the outputs | ||||
Fernando Perez
|
r1850 | docwriter.write_api_docs(outdir) | ||
Paul Ivanov
|
r11758 | # Write index with .txt extension - we can include it, but Sphinx won't try | ||
Thomas Kluyver
|
r9244 | # to compile it | ||
Paul Ivanov
|
r11758 | docwriter.write_index(outdir, 'gen.txt', | ||
Fernando Perez
|
r1850 | relative_to = pjoin('source','api') | ||
) | ||||
MinRK
|
r11213 | print ('%d files written' % len(docwriter.written_modules)) | ||