Some rst and configuration fixes.

docs/source/conf.py

@@ -1,273 +1,282 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.io/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__',
             })
 else:
     import sphinx_rtd_theme
     html_theme = "sphinx_rtd_theme"
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # 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',
     'sphinx.ext.napoleon',  # 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':
+def is_stable(extra):
+    for ext in {'dev', 'b', 'rc'}:
+        if ext in extra:
+            return False
+    return True
+
+if is_stable(iprelease['_version_extra']):
+    tags.add('ipystable')
+else:
+    tags.add('ipydev')
     rst_prolog = """
-    .. note::
+    .. warning::
 
         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'
 html_favicon = 'favicon.ico'
 
 # 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/3/', None),
                        'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None),
                        'traitlets': ('http://traitlets.readthedocs.io/en/latest/', None),
                        'jupyterclient': ('http://jupyter-client.readthedocs.io/en/latest/', None),
                        'ipyparallel': ('http://ipyparallel.readthedocs.io/en/latest/', None),
                        'jupyter': ('http://jupyter.readthedocs.io/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

docs/source/whatsnew/version5.rst

@@ -1,163 +1,164 b''
 ============
  5.x Series
 ============
 
 IPython 5.0
 ===========
 
 Released June, 2016
 
 IPython 5.0 now uses `prompt-toolkit` for the command line interface, thus
 allowing real multi-line editing and syntactic coloration as you type.
 
 
 When using IPython as a subprocess, like for emacs inferior-shell, IPython can
 be started with --simple-prompt flag, which will bypass the prompt_toolkit
 input layer. In this mode completion, prompt color and many other features are
 disabled.
 
 Backwards incompatible changes
 ------------------------------
 
 
 The `install_ext magic` function which was deprecated since 4.0 have now been deleted.
 You can still distribute and install extension as packages on PyPI.
 
 Update IPython event triggering to ensure callback registration and
 unregistration only affects the set of callbacks the *next* time that event is
 triggered. See :ghissue:`9447` and :ghpull:`9453`.
 
 This is a change to the existing semantics, wherein one callback registering a
 second callback when triggered for an event would previously be invoked for
 that same event.
 
 Integration with pydb has been removed since pydb development has been stopped
 since 2012, and pydb is not installable from PyPI
 
 
 
 Replacement of readline in TerminalInteractiveShell and PDB
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 IPython 5.0 now uses ``prompt_toolkit``. The
 ``IPython.terminal.interactiveshell.TerminalInteractiveShell`` now uses
 ``prompt_toolkit``. It is an almost complete rewrite, so many settings have
 thus changed or disappeared. The class keep the same name to avoid breaking
 user configuration for the options which names is unchanged.
 
 The usage of ``prompt_toolkit`` is accompanied by a complete removal of all
 code, using ``readline``. A particular effect of not using `readline` anymore
 is that `.inputrc` settings are note effective anymore. Options having similar
 effects have likely been replaced by a configuration option on IPython itself
 (e.g: vi input mode).
 
 The `PromptManager` class have been removed, and the prompt machinery simplified.
 See `TerminalInteractiveShell.prompts` configurable for how to setup your prompts.
 
 .. note::
 
     During developement and beta cycle, ``TerminalInteractiveShell`` was
     temporarly moved to ``IPtyhon.terminal.ptshell``.
 
 
 Most of the above remarks also affect `IPython.core.debugger.Pdb`, the `%debug`
 and `%pdb` magic which do not use readline anymore either.
 
 The color handling has been slightly changed and is now exposed
 through, in particular the colors of prompts and as you type
 highlighting can be affected by :
 ``TerminalInteractiveShell.highlight_style``. With default
 configuration the ``--colors`` flag and ``%colors`` magic behavior
 should be mostly unchanged. See the `colors <termcolour>`_ section of
 our documentation
 
 Provisional Changes
 -------------------
 
 Provisional changes are in experimental functionality that may, or may not make
 it to future version of IPython, and which API may change without warnings.
 Activating these feature and using these API is at your own risk, and may have
 security implication for your system, especially if used with the Jupyter notebook,
 
 When running via the Jupyter notebook interfaces, or other compatible client,
 you can enable rich documentation experimental functionality:
 
 When the ``docrepr`` package is installed setting the boolean flag
 ``InteractiveShell.sphinxify_docstring`` to ``True``, will process the various
 object through sphinx before displaying them (see the ``docrepr`` package
 documentation for more information.
 
 You need to also enable the IPython pager display rich HTML representation
 using the ``InteractiveShell.enable_html_pager`` boolean configuration option.
 As usual you can set these configuration options globally in your configuration
 files, alternatively you can turn them on dynamically using the following
 snippet:
 
 .. code-block:: python
 
     ip = get_ipython()
     ip.sphinxify_docstring = True
     ip.enable_html_pager = True
 
+
 You can test the effect of various combinations of the above configuration in
 the Jupyter notebook, with things example like :
 
-.. code-block:: python
+.. code-block:: ipython
 
     import numpy as np
     np.histogram?
 
+
 This is part of an effort to make Documentation in Python richer and provide in
 the long term if possible dynamic examples that can contain math, images,
 widgets... As stated above this is nightly experimental feature with a lot of
 (fun) problem to solve. We would be happy to get your feedback and expertise on
 it.
 
 
 Removed Feature
 ---------------
 
- - ``TerminalInteractiveShell.autoedit_syntax`` Has been broken for many years now
-apparently. It has been removed.
+- ``TerminalInteractiveShell.autoedit_syntax`` Has been broken for many years now
+  apparently. It has been removed.
 
 
 Deprecated Features
 -------------------
 
-Some deprecated feature, don't forget to enable `DeprecationWarning` as error
+Some deprecated feature, don't forget to enable ``DeprecationWarning`` as error
 of you are using IPython in Continuous Integration setup or in your testing in general:
 
-.. code::
-    :python:
+.. code-block:: python
 
     import warnings
     warnings.filterwarnings('error', '.*', DeprecationWarning, module='yourmodule.*')
 
 
- - `hooks.fix_error_editor` seem to be unused and is pending deprecation.
- - `IPython/core/excolors.py:ExceptionColors` is  deprecated.
- - `IPython.core.InteractiveShell:write()` is deprecated, use `sys.stdout` instead.
- - `IPython.core.InteractiveShell:write_err()` is deprecated, use `sys.stderr` instead.
- - The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has now no effects.
- - The `global_ns` keyword argument of IPython Embed was deprecated, and  will now have no effect. Use `module` keyword argument instead.
+- ``hooks.fix_error_editor`` seem to be unused and is pending deprecation.
+- `IPython/core/excolors.py:ExceptionColors` is  deprecated.
+- `IPython.core.InteractiveShell:write()` is deprecated, use `sys.stdout` instead.
+- `IPython.core.InteractiveShell:write_err()` is deprecated, use `sys.stderr` instead.
+- The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has now no effects.
+- The `global_ns` keyword argument of IPython Embed was deprecated, and  will now have no effect. Use `module` keyword argument instead.
 
 
 Known Issues:
 -------------
 
- - ``<Esc>`` Key does not dismiss the completer and does not clear the current
-   buffer. This is an on purpose modification due to current technical
-   limitation. Cf :ghpull:`9572`. Escape the control character which is used
-   for other shortcut, and there is no practical way to distinguish. Use Ctr-G
-   or Ctrl-C as an alternative. 
+- ``<Esc>`` Key does not dismiss the completer and does not clear the current
+  buffer. This is an on purpose modification due to current technical
+  limitation. Cf :ghpull:`9572`. Escape the control character which is used
+  for other shortcut, and there is no practical way to distinguish. Use Ctr-G
+  or Ctrl-C as an alternative.
 
- - Cannot use ``Shift-Enter`` and ``Ctrl-Enter`` to submit code in terminal. cf
-   :ghissue:`9587` and :ghissue:`9401`. In terminal there is no practical way to
-   distinguish these key sequences from a normal new line return. 
+- Cannot use ``Shift-Enter`` and ``Ctrl-Enter`` to submit code in terminal. cf
+  :ghissue:`9587` and :ghissue:`9401`. In terminal there is no practical way to
+  distinguish these key sequences from a normal new line return.
 
- - ``PageUp`` and ``pageDown`` do not move through completion menu.
+- ``PageUp`` and ``pageDown`` do not move through completion menu.
 
- - Color styles might not adapt to terminal emulator themes. This will need new
-   version of Pygments to be released, and can be mitigated with custom themes. 
+- Color styles might not adapt to terminal emulator themes. This will need new
+  version of Pygments to be released, and can be mitigated with custom themes.