Merge pull request #8714 from minrk/confhacks

Run autogen scripts on readthedocs

docs/autogen_api.py

@@ -1,72 +1,76 b''
 #!/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'))
+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__':
-    pjoin = os.path.join
     package = 'IPython'
-    outdir = pjoin('source','api','generated')
+    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',
                                         ]
 
     # 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',
                                         # Deprecated:
                                         r'\.core\.magics\.deprecated',
                                         # 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',
                                         ]
     # 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.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')
+                          relative_to = pjoin(source, 'api')
                           )
     print ('%d files written' % len(docwriter.written_modules))

docs/autogen_config.py

@@ -1,29 +1,35 b''
 #!/usr/bin/env python
 
+from os.path import join, dirname, abspath
+
 from IPython.terminal.ipapp import TerminalIPythonApp
 from ipykernel.kernelapp import IPKernelApp
 
+here = abspath(dirname(__file__))
+options = join(here, 'source', 'config', 'options')
+generated = join(options, 'generated.rst')
+
 def write_doc(name, title, app, preamble=None):
     filename = '%s.rst' % name
-    with open('source/config/options/%s' % filename, 'w') as f:
+    with open(join(options, filename), 'w') as f:
         f.write(title + '\n')
         f.write(('=' * len(title)) + '\n')
         f.write('\n')
         if preamble is not None:
             f.write(preamble + '\n\n')
         f.write(app.document_config_options())
-    with open('source/config/options/generated', 'a') as f:
+    with open(generated, 'a') as f:
         f.write(filename + '\n')
 
 
 if __name__ == '__main__':
     # create empty file
-    with open('source/config/options/generated', 'w'):
+    with open(generated, 'w'):
         pass
 
     write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp())
     write_doc('kernel', 'IPython kernel options', IPKernelApp(),
         preamble=("These options can be used in :file:`ipython_kernel_config.py`. "
                   "The kernel also respects any options in `ipython_config.py`"),
     )
 

docs/autogen_magics.py

@@ -1,64 +1,68 b''
+import os
+
 from IPython.core.alias import Alias
 from IPython.core.interactiveshell import InteractiveShell
 from IPython.core.magic import MagicAlias
 from IPython.utils.text import dedent, indent
 
 shell = InteractiveShell.instance()
 magics = shell.magics_manager.magics
 
 def _strip_underline(line):
     chars = set(line.strip())
     if len(chars) == 1 and ('-' in chars or '=' in chars):
         return ""
     else:
         return line
 
 def format_docstring(func):
     docstring = (func.__doc__ or "Undocumented").rstrip()
     docstring = indent(dedent(docstring))
     # Sphinx complains if indented bits have rst headings in, so strip out
     # any underlines in the docstring.
     lines = [_strip_underline(l) for l in docstring.splitlines()]
     return "\n".join(lines)
 
 output = [
 "Line magics",
 "===========",
 "",
 ]
 
 # Case insensitive sort by name
 def sortkey(s): return s[0].lower()
 
 for name, func in sorted(magics['line'].items(), key=sortkey):
     if isinstance(func, Alias) or isinstance(func, MagicAlias):
         # Aliases are magics, but shouldn't be documented here
         # Also skip aliases to other magics
         continue
     output.extend([".. magic:: {}".format(name),
                    "",
                    format_docstring(func),
                    ""])
 
 output.extend([
 "Cell magics",
 "===========",
 "",
 ])
 
 for name, func in sorted(magics['cell'].items(), key=sortkey):
     if name == "!":
         # Special case - don't encourage people to use %%!
         continue
     if func == magics['line'].get(name, 'QQQP'):
         # Don't redocument line magics that double as cell magics
         continue
     if isinstance(func, MagicAlias):
         continue
     output.extend([".. cellmagic:: {}".format(name),
                    "",
                    format_docstring(func),
                    ""])
 
-with open("source/interactive/magics-generated.txt", "w") as f:
-    f.write("\n".join(output))
  No newline at end of file
+here = os.path.dirname(__file__)
+dest = os.path.join(here, 'source', 'interactive', 'magics-generated.txt')
+with open(dest, "w") as f:
+    f.write("\n".join(output))

docs/requirements.txt

@@ -1,2 +1,3 b''
 numpydoc
 -e .
+ipykernel

docs/source/conf.py

@@ -1,256 +1,266 b''
 # -*- coding: utf-8 -*-
 #
 # IPython documentation build configuration file.
 
 # NOTE: This file has been edited manually from the auto-generated one from
 # sphinx.  Do NOT delete and re-generate.  If any changes from sphinx are
 # needed, generate a scratch one and merge by hand any new fields needed.
 
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # The contents of this file are pickled, so don't put values in the namespace
 # that aren't pickleable (module imports are okay, they're removed automatically).
 #
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
 import sys, os
 
 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
 
 if ON_RTD:
     # Mock the presence of matplotlib, which we don't have on RTD
     # see
     # http://read-the-docs.readthedocs.org/en/latest/faq.html
     tags.add('rtd')
-    
+
+    # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
+    for name in ('config', 'api', 'magics'):
+        fname = 'autogen_{}.py'.format(name)
+        fpath = os.path.abspath(os.path.join('..', fname))
+        with open(fpath) as f:
+            exec(compile(f.read(), fname, 'exec'), {
+                '__file__': fpath,
+                '__name__': '__main__',
+            })
+
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 # We load the ipython release info into a dict by explicit execution
 iprelease = {}
 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease)
 
 # General configuration
 # ---------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.only_directives',
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.intersphinx',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'numpydoc',  # to preprocess docstrings
     'github',  # for easy GitHub links
     'magics',
 ]
 
 if ON_RTD:
     # Remove extensions not currently supported on RTD
     extensions.remove('matplotlib.sphinxext.only_directives')
     extensions.remove('matplotlib.sphinxext.mathmpl')
     extensions.remove('matplotlib.sphinxext.plot_directive')
     extensions.remove('IPython.sphinxext.ipython_directive')
     extensions.remove('IPython.sphinxext.ipython_console_highlighting')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 if iprelease['_version_extra'] == 'dev':
     rst_prolog = """
     .. note::
 
         This documentation is for a development version of IPython. There may be
         significant differences from the latest stable release.
 
     """
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
 copyright = 'The IPython Development Team'
 
 # ghissue config
 github_project_url = "https://github.com/ipython/ipython"
 
 # numpydoc config
 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
 numpydoc_class_members_toctree = False
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 # The full version, including alpha/beta/rc tags.
 release = "%s" % iprelease['version']
 # Just the X.Y.Z part, no '-dev'
 version = iprelease['version'].split('-', 1)[0]
 
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
 # Exclude these glob-style patterns when looking for source files. They are
 # relative to the source/ directory.
 exclude_patterns = ['whatsnew/pr']
 
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # Set the default role so we can use `foo` instead of ``foo``
 default_role = 'literal'
 
 # Options for HTML output
 # -----------------------
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
 html_style = 'default.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
 #html_logo = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 html_additional_pages = {
     'interactive/htmlnotebook': 'notebook_redirect.html',
     'interactive/notebook': 'notebook_redirect.html',
     'interactive/nbconvert': 'notebook_redirect.html',
     'interactive/public_server': 'notebook_redirect.html',
 }
 
 # If false, no module index is generated.
 #html_use_modindex = True
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ipythondoc'
 
 intersphinx_mapping = {'python': ('http://docs.python.org/2/', None),
                        'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None),
                        'traitlets': ('http://traitlets.readthedocs.org/en/latest/', None),
                        'jupyterclient': ('http://jupyter-client.readthedocs.org/en/latest/', None),
                       }
 
 # Options for LaTeX output
 # ------------------------
 
 # The paper size ('letter' or 'a4').
 latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
 latex_font_size = '11pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 
 latex_documents = [
     ('index', 'ipython.tex', 'IPython Documentation',
      u"""The IPython Development Team""", 'manual', True),
     ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
      'Using IPython on Windows HPC Server 2008',
      u"Brian E. Granger", 'manual', True)
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 #latex_use_parts = False
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
 latex_use_modindex = True
 
 
 # Options for texinfo output
 # --------------------------
 
 texinfo_documents = [
   (master_doc, 'ipython', 'IPython Documentation',
    'The IPython Development Team',
    'IPython',
    'IPython Documentation',
    'Programming',
    1),
 ]
 
 modindex_common_prefix = ['IPython.']
 
 
 # Cleanup
 # -------
 # delete release info to avoid pickling errors from sphinx
 
 del iprelease