add codename to sphinx index and what's new

docs/source/conf.py

@@ -1,228 +1,229 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')
     
 # 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'))
 
 # Import support for ipython console session syntax highlighting
 # (lives IPython's sphinxext subpackage)
 from IPython.sphinxext import ipython_console_highlighting
 
 # We load the ipython release info into a dict by explicit execution
 iprelease = {}
 execfile('../../IPython/core/release.py',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.doctest',
     'sphinx.ext.inheritance_diagram',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'numpydoc',  # to preprocess docstrings
     'github',  # for easy GitHub links
 ]
 
 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')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
 copyright = '2008, The IPython Development Team'
 
 # ghissue config
 github_project_url = "https://github.com/ipython/ipython"
 
 # 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 = iprelease['version']
-# The short X.Y version.
-version = '.'.join(release.split('.',2)[:2])
+codename = iprelease['codename']
+release = "%s: %s" % (iprelease['version'], codename)
+# 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 = []
 
 # List of directories, relative to source directories, that shouldn't be searched
 # for source files.
 exclude_dirs = ['attic']
 
 # 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'
 
 
 # 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 = {}
 
 # 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'
 
 
 # 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',
      ur"""The IPython Development Team""", 'manual', True),
     ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
      'Using IPython on Windows HPC Server 2008',
      ur"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),
 ]
 
 
 # Cleanup
 # -------
 # delete release info to avoid pickling errors from sphinx
 
 del iprelease

docs/source/whatsnew/version1.0.rst

@@ -1,287 +1,288 b''
 ============
  1.0 Series
 ============
 
-Release 1.0
-===========
+Release 1.0.0: An Afternoon Hack
+================================
+
 
 IPython 1.0 requires Python ≥ 2.6.5 or ≥ 3.2.1.
 It does not support Python 3.0, 3.1, or 2.5.
 
 This is a big release.  The principal milestone is the addition of :mod:`IPython.nbconvert`,
 but there has been a great deal of work improving all parts of IPython as well.
 
 The previous version (0.13) was released on June 30, 2012,
 and in this development cycle we had:
 
 - ~12 months of work.
 - ~700 pull requests merged.
 - ~600 issues closed (non-pull requests).
 - contributions from ~150 authors.
 - ~4000 commits.
 
 The amount of work included in this release is so large that we can only cover
 here the main highlights; please see our :ref:`detailed release statistics
 <issues_list_100>` for links to every issue and pull request closed on GitHub
 as well as a full list of individual contributors.
 It includes
 
 Reorganization
 --------------
 
 There have been two major reorganizations in IPython 1.0:
 
 - Added :mod:`IPython.kernel` for all kernel-related code.
   This means that :mod:`IPython.zmq` has been removed,
   and much of it is now in :mod:`IPython.kernel.zmq`,
   some of it being in the top-level :mod:`IPython.kernel`.
 - We have removed the `frontend` subpackage,
   as it caused unnecessary depth.  So what was :mod:`IPython.frontend.qt`
   is now :mod:`IPython.qt`, and so on.  The one difference is that
   the notebook has been further flattened, so that
   :mod:`IPython.frontend.html.notebook` is now just `IPython.html`.
   There is a shim module, so :mod:`IPython.frontend` is still
   importable in 1.0, but there will be a warning.
 - The IPython sphinx directives are now installed in :mod:`IPython.sphinx`,
   so they can be imported by other projects.
 
 
 Public APIs
 -----------
 
 For the first time since 0.10 (sorry, everyone),
 there is an official public API for starting IPython:
 
 .. sourcecode:: python
 
     from IPython import start_ipython
     start_ipython()
 
 This is what packages should use that start their own IPython session,
 but don't actually want embedded IPython (most cases).
 
 We also have added:
 
 .. sourcecode:: python
 
     from IPython import get_ipython
 
 
 Which is a *library* function for getting the current IPython instance,
 and will return ``None`` if no IPython instance is running.
 This is the official way to check whether your code is called from inside an IPython session.
 If you want to check for IPython without unnecessarily importing IPython,
 use this function:
 
 .. sourcecode:: python
 
     def get_ipython():
         """return IPython instance if there is one, None otherwise"""
         import sys
         if "IPython" in sys.modules:
             import IPython
             return IPython.get_ipython()
 
 Core
 ----
 
 - The input transformation framework has been reworked. This fixes some corner
   cases, and adds more flexibility for projects which use IPython, like SymPy &
   SAGE. For more details, see :doc:`/config/inputtransforms`.
 - Exception types can now be displayed with a custom traceback, by defining a
   ``_render_traceback_()`` method which returns a list of strings, each
   containing one line of the traceback.
 - A new command, ``ipython history trim`` can be used to delete everything but
   the last 1000 entries in the history database.
 - ``__file__`` is defined in both config files at load time,
   and ``.ipy`` files executed with ``%run``.
 - ``%logstart`` and ``%logappend`` are no longer broken.
 - Add glob expansion for ``%run``, e.g. ``%run -g script.py *.txt``.
 - Expand variables (``$foo``) in Cell Magic argument line.
 - By default, :command:`iptest` will exclude various slow tests.
   All tests can be run with :command:`iptest --all`.
 - SQLite history can be disabled in the various cases that it does not behave well.
 - ``%edit`` works on interactively defined variables.
 - editor hooks have been restored from quarantine, enabling TextMate as editor,
   etc.
 - The env variable PYTHONSTARTUP is respected by IPython.
 - A ``%matplotlib`` magic is added, which is like the old ``%pylab`` magic,
   but it does not import anything to the interactive namespace.
   It is recommended that users switch to ``%matplotlib`` and explicit imports.
 
 
 Backwards incompatible changes
 ******************************
 
 - Calling :meth:`InteractiveShell.prefilter` will no longer perform static
   transformations - the processing of escaped commands such as ``%magic`` and
   ``!system``, and stripping input prompts from code blocks. This functionality
   was duplicated in :mod:`IPython.core.inputsplitter`, and the latter version
   was already what IPython relied on. A new API to transform input will be ready
   before release.
 - Functions from :mod:`IPython.lib.inputhook` to control integration with GUI
   event loops are no longer exposed in the top level of :mod:`IPython.lib`.
   Code calling these should make sure to import them from
   :mod:`IPython.lib.inputhook`.
 - For all kernel managers, the ``sub_channel`` attribute has been renamed to
   ``iopub_channel``.
 - Users on Python versions before 2.6.6, 2.7.1 or 3.2 will now need to call
   :func:`IPython.utils.doctestreload.doctest_reload` to make doctests run 
   correctly inside IPython. Python releases since those versions are unaffected.
   For details, see :ghpull:`3068` and `Python issue 8048 <http://bugs.python.org/issue8048>`_.
 - The ``InteractiveShell.cache_main_mod()`` method has been removed, and
   :meth:`~IPython.core.interactiveshell.InteractiveShell.new_main_mod` has a
   different signature, expecting a filename where earlier versions expected
   a namespace. See :ghpull:`3555` for details.
 - The short-lived plugin system has been removed. Extensions are the way to go.
 
 
 NbConvert
 ---------
 
 The major milestone for IPython 1.0 is the addition of :mod:`IPython.nbconvert` - tools for converting
 IPython notebooks to various other formats.
 
 .. warning::
 
     nbconvert is α-level preview code in 1.0
 
 To use nbconvert to convert various file formats::
 
     ipython nbconvert --format full_html *.ipynb
 
 See ``ipython nbconvert --help`` for more information.
 nbconvert depends on `pandoc`_ for many of the translations to and from various formats.
 
 .. _pandoc: http://johnmacfarlane.net/pandoc/
 
 Notebook
 --------
 
 Major changes to the IPython Notebook in 1.0:
 
 - The notebook is now autosaved, by default at an interval of two minutes.
   When you press 'save' or Ctrl-S, a *checkpoint* is made, in a hidden folder.
   This checkpoint can be restored, so that the autosave model is strictly safer
   than traditional save. If you change nothing about your save habits,
   you will always have a checkpoint that you have written,
   and an autosaved file that is kept up to date.
 - You can load custom javascript and CSS in the notebook by editing the files
   :file:`$(ipython locate profile)/static/custom/custom.{js,css}`.
 - Add ``%%html``, ``%%svg``, ``%%javascript``, and ``%%latex`` cell magics
   for writing raw output in notebook cells.
 - add a redirect handler and anchors on heading cells, so you can link
   across notebooks, directly to heading cells in other notebooks.
 - Images support width and height metadata,
   and thereby 2x scaling (retina support).
 - ``_repr_foo_`` methods can return a tuple of (data, metadata),
   where metadata is a dict containing metadata about the displayed object.
   This is used to set size, etc. for retina graphics. To enable retina matplotlib figures,
   simply set ``InlineBackend.figure_format = 'retina'`` for 2x PNG figures.
 - Add display.FileLink and FileLinks for quickly displaying HTML links to local files.
 - Cells have metadata, which can be edited via cell toolbars.
   This metadata can be used by external code (e.g. reveal.js or exporters),
   when examining the notebook.
 - Fix an issue parsing LaTeX in markdown cells, which required users to type ``\\\``,
   instead of ``\\``.
 - Notebook templates are rendered with Jinja instead of Tornado.
 - ``%%file`` has been renamed ``%%writefile`` (``%%file``) is deprecated.
 - ANSI (and VT100) color parsing has been improved in both performance and
   supported values.
 - The static files path can be found as ``IPython.html.DEFAULT_STATIC_FILES_PATH``,
   which may be changed by package managers.
 - The notebook supports :func:`raw_input`, and thus also ``%debug``.
 - IPython's CSS is installed in :file:`static/css/style.min.css`
   (all style, including bootstrap), and :file:`static/css/ipython.min.css`,
   which only has IPython's own CSS. The latter file should be useful for embedding
   IPython notebooks in other pages, blogs, etc.
 
 Javascript Components
 *********************
 
 The javascript components used in the notebook have been updated significantly.
 
 - updates to jQuery (2.0) and jQueryUI (1.10)
 - Update CodeMirror to 3.14
 - Twitter Bootstrap (2.3) for layout
 - Font-Awesome (3.1) for icons
 - highlight.js (7.3) for syntax highlighting
 - marked (0.2.8) for markdown rendering
 - require.js (2.1) for loading javascript
 
 Some relevant changes that are results of this:
 
 - Markdown cells now support GitHub-flavored Markdown (GFM),
 which includes ``\`\`\`python`` code blocks and tables.
 - Notebook UI behaves better on more screen sizes.
 - Various code cell input issues have been fixed.
 
 
 Kernel
 ------
 
 The kernel code has been substantially reorganized.
 
 New features in the kernel:
 
 - Kernels support ZeroMQ IPC transport, not just TCP
 - The message protocol has added a top-level metadata field,
   used for information about messages.
 - Add a `data_pub` message that functions much like `display_pub`,
   but publishes raw (usually pickled) data, rather than representations.
 - Ensure that ``sys.stdout.encoding`` is defined in Kernels.
 - Stdout from forked subprocesses should be forwarded to frontends (instead of crashing).
 
 IPEP 13
 *******
 
 The KernelManager has been split into a :class:`~.KernelManager` and a :class:`~.KernelClient`.
 The Manager owns a kernel and starts / signals / restarts it. There is always zero or one
 KernelManager per Kernel.  Clients communicate with Kernels via zmq channels,
 and there can be zero-to-many Clients connected to a Kernel at any given time.
 
 The KernelManager now automatically restarts the kernel when it dies,
 rather than requiring user input at the notebook or QtConsole UI
 (which may or may not exist at restart time).
 
 In-process kernels
 ******************
 
 The Python-language frontends, particularly the Qt console, may now communicate
 with in-process kernels, in addition to the traditional out-of-process
 kernels. An in-process kernel permits direct access to the kernel namespace,
 which is necessary in some applications. It should be understood, however, that
 the in-process kernel is not robust to bad user input and will block the main
 (GUI) thread while executing. Developers must decide on a case-by-case basis
 whether this tradeoff is appropriate for their application.
 
 
 
 Parallel
 --------
 
 IPython.parallel has had some refactoring as well.  
 There are many improvements and fixes, but these are the major changes:
 
 - Connections have been simplified. All ports and the serialization in use
   are written to the connection file, rather than the initial two-stage system.
 - Serialization has been rewritten, fixing many bugs and dramatically improving
   performance serializing large containers.
 - Load-balancing scheduler performance with large numbers of tasks has been dramatically improved.
 - There should be fewer (hopefully zero) false-positives for engine failures.
 - Increased compatibility with various use cases that produced serialization / argument errors
   with map, etc.
 - The controller can attempt to resume operation if it has crashed,
   by passing ``ipcontroller --restore``.
 - Engines can monitor the Hub heartbeat, and shutdown if the Hub disappears for too long.
 - add HTCondor support in launchers
 
 
 QtConsole
 ---------
 
 Various fixes, including improved performance with lots of text output,
 and better drag and drop support.
 The initial window size of the qtconsole is now configurable via ``IPythonWidget.width``
 and ``IPythonWidget.height``.