a few fixes

- default back tom Mathjax2.0
- install to profile by default
- fix in doc
- fix bad return

IPython/external/mathjax.py

@@ -1,266 +1,268
 """Utility function for installing MathJax javascript library into
 the notebook's 'static' directory, for offline use.
 
+ Authors:
+
+ * Min RK
+ * Mark Sienkiewicz
+ * Matthias Bussonnier
+
 To download and install MathJax:
 
 From Python:
 
     >>> from IPython.external.mathjax import install_mathjax
     >>> install_mathjax()
 
 From the command line:
 
     $ python -m IPython.external.mathjax
 
 To install MathJax from a file you have already downloaded:
 
     $ python -m IPython.external.mathjax mathjax-xxx.tar.gz
     $ python -m IPython.external.mathjax mathjax-xxx.zip
 
 It will not install MathJax if it is already there.  Use -r to
 replace the existing copy of MathJax.
 
 To find the directory where IPython would like MathJax installed:
 
     $ python -m IPython.external.mathjax -d
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
-# Authors:
-# 
-# * Min RK
-# * Mark Sienkiewicz at Space Telescope Science Institute (command line invocation)
-#
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import shutil
 import sys
 import tarfile
 import urllib2
 import zipfile
 
-from IPython.frontend.html import notebook as nbmod
-
 #-----------------------------------------------------------------------------
 #
 #-----------------------------------------------------------------------------
 
 # Where mathjax will be installed.
 
-static = os.path.join(os.path.dirname(os.path.abspath(nbmod.__file__)), 'static')
-dest = os.path.join(static, 'mathjax')
+dest = os.path.join(locate_profile('default'), 'static')
 
 ##
 
 # Test for access to install mathjax.
 
 def check_perms(replace=False):
     if not os.access(static, os.W_OK):
         raise IOError("Need have write access to %s"%static)
     if os.path.exists(dest):
         if replace:
             if not os.access(dest, os.W_OK):
                 raise IOError("Need have write access to %s"%dest)
             print "removing previous MathJax install"
             shutil.rmtree(dest)
             return True
         else:
             print "offline MathJax apparently already installed"
             return False
     else :
         return True
 
 ##
 
 def extract_tar( fd, dest ) :
     # use 'r|gz' stream mode, because socket file-like objects can't seek:
     tar = tarfile.open(fileobj=fd, mode='r|gz')
 
     # we just happen to know that the first entry in the mathjax
     # archive is the directory that the remaining members are in.
     topdir = tar.firstmember.path
 
     # extract the archive (contains a single directory) to the static/ directory
     tar.extractall(static)
 
     # it will be mathjax-MathJax-<sha>, rename to just mathjax
     os.rename(os.path.join(static, topdir), dest)
 
 ##
 
 def extract_zip( fd, dest ) :
     z = zipfile.ZipFile( fd, 'r' )
 
     # we just happen to know that the first entry in the mathjax
     # archive is the directory that the remaining members are in.
     topdir = z.namelist()[0]
 
     # extract the archive (contains a single directory) to the static/ directory
     z.extractall( static )
 
     # it will be mathjax-MathJax-<sha>, rename to just mathjax
     d = os.path.join(static, topdir)
     print d
     os.rename(os.path.join(static, topdir), dest)
 
 ##
 
-def install_mathjax(tag='v1.1', replace=False, fd=None, extractor=extract_tar ):
-    """Download and install MathJax for offline use.
+def install_mathjax(tag='v2.0', replace=False, file=None, extractor=extract_tar ):
+    """Download and/or install MathJax for offline use.
 
     This will install mathjax to the 'static' dir in the IPython notebook
     package, so it will fail if the caller does not have write access
     to that location.
 
     MathJax is a ~15MB download, and ~150MB installed.
 
     Parameters
     ----------
 
     replace : bool [False]
         Whether to remove and replace an existing install.
-    tag : str ['v1.1']
+    tag : str ['v2.0']
         Which tag to download. Default is 'v1.1', the current stable release,
         but alternatives include 'v1.1a' and 'master'.
+    file : file like object [ defualt to content of https://github.com/mathjax/MathJax/tarball/#{tag}]
+        File handle from which to untar/unzip/... mathjax
+    extractor : function
+        Method tu use to untar/unzip/... `file`
     """
 
     if not check_perms(replace) :
         return
 
-    if fd is None :
+    if file is None :
         # download mathjax
         mathjax_url = "https://github.com/mathjax/MathJax/tarball/%s"%tag
         print "Downloading mathjax source from %s"%mathjax_url
         response = urllib2.urlopen(mathjax_url)
-        fd = response.fp
+        file = response.fp
 
     print "Extracting to %s"%dest
     extractor( fd, dest )
 
 ##
 
 def test_func( remove ) :
     """See if mathjax appears to be installed correctly"""
     if not os.path.isdir( dest ) :
         print "%s directory not found"%dest
         status=1
     if not os.path.exists( dest + "/MathJax.js" ) :
         print "MathJax.js not present in %s"%dest
         status=1
     print "ok"
     if remove :
         shutil.rmtree( dest )
-    return 0
+    return status
 
 ##
 
 def main( args ) :
     # This main is just simple enough that it is not worth the
     # complexity of argparse
 
     # What directory is mathjax in?
     if '-d' in args :
         print dest
         return
 
     # help
     if '-h' in args or '--help' in args :
         print __doc__
         return
 
     # remove/replace existing mathjax?
     if '-r' in args :
         replace = True
         args.remove('-r')
     else :
         replace = False
 
     # undocumented test interface
     if '-test' in args :
         return test_func( replace )
 
     # do it 
     if len(args) == 0 :
         # This is compatible with the interface documented in ipython 0.13
         install_mathjax( replace=replace )
     else :
         fname = args[0]
 
         # automatically detect zip/tar - could do something based
 	    # on file content, but really not cost-effective here.
         if fname.endswith('.zip') :
             extractor = extract_zip
         else :
             extractor = extract_tar
 
         # do it
         install_mathjax(fd=open(args[0],"r"), replace=replace, extractor=extractor )
 
 if __name__ == '__main__' :
     sys.exit(main( sys.argv[1:] ))
 
 __all__ = ['install_mathjax','main','dest']
 
 """
 Test notes:
 
 IPython uses IPython.testing.iptest as a custom test controller
 (though it is based on nose).  It might be possible to fit automatic
 tests of installation into that framework, but it looks awkward to me.
 So, here is a manual procedure for testing this automatic installer.
 
     Mark Sienkiewicz, 2012-08-06
     first 8 letters of my last name @ stsci.edu
 
 # remove mathjax from the installed ipython instance
 # IOError ok if mathjax was never installed yet.
 
 python -m IPython.external.mathjax -test -r
 
 # download and install mathjax from command line:
 
 python -m IPython.external.mathjax 
 python -m IPython.external.mathjax -test -r
 
 # download and install from within python
 
 python -c "from IPython.external.mathjax import install_mathjax; install_mathjax()"
 python -m IPython.external.mathjax -test -r
 
 # view http://www.mathjax.org/download/ in your browser
 # save-as the link for MathJax-1.1 near the bottom of the page.
 # The file it offers is mathjax-MathJax-v1.1-0-g5a7e4d7.zip
 
 python -m IPython.external.mathjax mathjax-MathJax-v1.1-0-g5a7e4d7.zip
 python -m IPython.external.mathjax -test -r
 
 # download https://github.com/mathjax/MathJax/tarball/v1.1 in your browser
 # (this is the url used internally by install_mathjax)
 # The file it offers is mathjax-MathJax-v1.1-0-g5a7e4d7.tar.gz
 
 python -m IPython.external.mathjax mathjax-MathJax-v1.1-0-g5a7e4d7.tar.gz 
 
 python -m IPython.external.mathjax -test
         # note no -r 
 
 # install it again while it is already there
 
 python -m IPython.external.mathjax mathjax-MathJax-v1.1-0-g5a7e4d7.tar.gz 
     # says "offline MathJax apparently already installed"
 
 python -m IPython.external.mathjax  ~/mathjax-MathJax-v1.1-0-g5a7e4d7.tar.gz
 python -m IPython.external.mathjax -test
 
 
 """

docs/source/install/install.txt

@@ -1,387 +1,388
 Overview
 ========
 
 This document describes the steps required to install IPython.  IPython is
 organized into a number of subpackages, each of which has its own dependencies.
 All of the subpackages come with IPython, so you don't need to download and
 install them separately.  However, to use a given subpackage, you will need to
 install all of its dependencies.
 
 Please let us know if you have problems installing IPython or any of its
 dependencies. Officially, IPython requires Python 2.6, 2.7, 3.1, or 3.2.
 
 .. warning::
 
     Since version 0.11, IPython has a hard syntax dependency on 2.6, and will no
     longer work on Python <= 2.5. You can find older versions of IPython which
     supported Python <= 2.5 `here <http://archive.ipython.org/release/>`_
 
 Some of the installation approaches use the :mod:`distribute` package and its
 :command:`easy_install` command line program.  In many scenarios, this provides
 the most simple method of installing IPython and its dependencies.  More
 information about :mod:`distribute` can be found on `its PyPI page
 <http://pypi.python.org/pypi/distribute>`__.
 
 .. note::
 
    On Windows, IPython has a hard dependency on :mod:`distribute`.  We hope to
    change this in the future, but for now on Windows, you *must* install
    :mod:`distribute`.
 
 More general information about installing Python packages can be found in
 `Python's documentation <http://docs.python.org>`_.
 
 
 Quickstart
 ==========
 
 If you have :mod:`distribute` installed and you are on OS X or Linux (not
 Windows), the following will download and install IPython *and* the main
 optional dependencies:
 
 .. code-block:: bash
 
     $ easy_install ipython[zmq,qtconsole,notebook,test]
 
 This will get:
 
 - pyzmq, needed for IPython's parallel computing features, qt console and
   notebook.
 - pygments, used by the Qt console for syntax highlighting.
 - tornado, needed by the web-based notebook
 - nose, used by the test suite.
 
 To run IPython's test suite, use the :command:`iptest` command:
 
 .. code-block:: bash
 
     $ iptest
 
     
 Installing IPython itself
 =========================
 
 Given a properly built Python, the basic interactive IPython shell will work
 with no external dependencies.  However, some Python distributions
 (particularly on Windows and OS X), don't come with a working :mod:`readline`
 module.  The IPython shell will work without :mod:`readline`, but will lack
 many features that users depend on, such as tab completion and command line
 editing.  If you install IPython with :mod:`distribute`, (e.g. with
 `easy_install`), then the appropriate :mod:`readline` for your platform will be
 installed.  See below for details of how to make sure you have a working
 :mod:`readline`.
 
 Installation using easy_install
 -------------------------------
 
 If you have :mod:`distribute` installed, the easiest way of getting IPython is
 to simply use :command:`easy_install`:
 
 .. code-block:: bash
 
     $ easy_install ipython
 
 That's it.
 
 Installation from source
 ------------------------
 
 If you don't want to use :command:`easy_install`, or don't have it installed,
 just grab the latest stable build of IPython from `here
 <http://ipython.org/download.html>`_.  Then do the following:
 
 .. code-block:: bash
 
     $ tar -xzf ipython.tar.gz
     $ cd ipython
     $ python setup.py install
 
 If you are installing to a location (like ``/usr/local``) that requires higher
 permissions, you may need to run the last command with :command:`sudo`.
 
 Windows
 -------
 
 As mentioned above, on Windows, IPython requires :mod:`distribute`, and it also
 requires the PyReadline library to properly support coloring and keyboard
 management (features that the default windows console doesn't have).  So on
 Windows, the installation procedure is:
 
 1. Install `distribute <http://pypi.python.org/pypi/distribute>`_.
 
 2. Install `pyreadline <http://pypi.python.org/pypi/pyreadline>`_.  You can use
    the command ``easy_install pyreadline`` from a terminal, or the binary
    installer appropriate for your platform from the PyPI page.
 
 3. Install IPython itself, which you can download from `PyPI
    <http://pypi.python.org/pypi/ipython>`_ or from `our site
    <http://ipython.org/download.html>`_.  Note that on Windows 7, you *must*
    right-click and 'Run as administrator' for the Start menu shortcuts to be
    created.
 
 IPython by default runs in a terminal window, but the normal terminal
 application supplied by Microsoft Windows is very primitive.  You may want to
 download the excellent and free Console_ application instead, which is a far
 superior tool.  You can even configure Console to give you by default an
 IPython tab, which is very convenient to create new IPython sessions directly
 from the working terminal.
 
 .. _Console:  http://sourceforge.net/projects/console
 
    
 Installing the development version
 ----------------------------------
 
 It is also possible to install the development version of IPython from our
 `Git <http://git-scm.com/>`_ source code repository.  To do this you will
 need to have Git installed on your system.  Then just do:
 
 .. code-block:: bash
 
     $ git clone https://github.com/ipython/ipython.git
     $ cd ipython
     $ python setup.py install
 
 Some users want to be able to follow the development branch as it changes.  If
 you have :mod:`distribute` installed, this is easy. Simply replace the last
 step by:
 
 .. code-block:: bash
 
     $ python setupegg.py develop
 
 This creates links in the right places and installs the command line script to
 the appropriate places.  Then, if you want to update your IPython at any time,
 just do:
 
 .. code-block:: bash
 
     $ git pull
 
     
 Basic optional dependencies
 ===========================
 
 There are a number of basic optional dependencies that most users will want to
 get.  These are:
 
 * readline (for command line editing, tab completion, etc.)
 * nose (to run the IPython test suite)
 * pexpect (to use things like irunner)
 
 If you are comfortable installing these things yourself, have at it, otherwise
 read on for more details.
 
 readline
 --------
 
 As indicated above, on Windows, PyReadline is a *mandatory* dependency.
 PyReadline is a separate, Windows only implementation of readline that uses
 native Windows calls through :mod:`ctypes`. The easiest way of installing
 PyReadline is you use the binary installer available `here
 <http://pypi.python.org/pypi/pyreadline>`_.
 
 On OSX, if you are using the built-in Python shipped by Apple, you will be
 missing a full readline implementation as Apple ships instead a library called
 ``libedit`` that provides only some of readline's functionality.  While you may
 find libedit sufficient, we have occasional reports of bugs with it and several
 developers who use OS X as their main environment consider libedit unacceptable
 for productive, regular use with IPython.
 
 Therefore, we *strongly* recommend that on OS X you get the full
 :mod:`readline` module.  We will *not* consider completion/history problems to
 be bugs for IPython if you are using libedit.
 
 To get a working :mod:`readline` module, just do (with :mod:`distribute`
 installed):
 
 .. code-block:: bash
 
     $ easy_install readline
 
 .. note::
 
     Other Python distributions on OS X (such as fink, MacPorts and the official
     python.org binaries) already have readline installed so you likely don't
     have to do this step.
 
 When IPython is installed with :mod:`distribute`, (e.g. using the
 ``easy_install`` command), readline is added as a dependency on OS X, and
 PyReadline on Windows, and will be installed on your system.  However, if you
 do not use distribute, you may have to install one of these packages yourself.
 
 
 nose
 ----
 
 To run the IPython test suite you will need the :mod:`nose` package.  Nose
 provides a great way of sniffing out and running all of the IPython tests.  The
 simplest way of getting nose, is to use :command:`easy_install`:
 
 .. code-block:: bash
 
     $ easy_install nose
 
 Another way of getting this is to do:
 
 .. code-block:: bash
 
     $ easy_install ipython[test]
 
 For more installation options, see the `nose website
 <http://somethingaboutorange.com/mrl/projects/nose/>`_.  
 
 Once you have nose installed, you can run IPython's test suite using the
 iptest command:
 
 .. code-block:: bash
 
     $ iptest
 
 pexpect
 -------
 
 The pexpect_ package is used in IPython's :command:`irunner` script, as well as
 for managing subprocesses. IPython now includes a version of pexpect in
 :mod:`IPython.external`, but if you have installed pexpect, IPython will use
 that instead. On Unix platforms (including OS X), just do:
 
 .. code-block:: bash
 
     $ easy_install pexpect
 
 Windows users are out of luck as pexpect does not run there.
 
 Dependencies for IPython.parallel (parallel computing)
 ======================================================
 
 :mod:`IPython.kernel` has been replaced by :mod:`IPython.parallel`, 
 which uses ZeroMQ for all communication.
 
 IPython.parallel provides a nice architecture for parallel computing, with a
 focus on fluid interactive workflows.  These features require just one package:
 PyZMQ.  See the next section for PyZMQ details.
 
 On a Unix style platform (including OS X), if you want to use
 :mod:`distribute`, you can just do:
 
 .. code-block:: bash
 
     $ easy_install ipython[zmq]    # will include pyzmq
 
 Security in IPython.parallel is provided by SSH tunnels.  By default, Linux
 and OSX clients will use the shell ssh command, but on Windows, we also
 support tunneling with paramiko_.
 
 Dependencies for IPython.zmq
 ============================
 
 pyzmq
 -----
 
 IPython 0.11 introduced some new functionality, including a two-process
 execution model using ZeroMQ_ for communication. The Python bindings to ZeroMQ
 are found in the PyZMQ_ project, which is easy_install-able once you have
 ZeroMQ installed.  If you are on Python 2.6 or 2.7 on OSX, or 2.7 on Windows,
 pyzmq has eggs that include ZeroMQ itself.
 
 IPython.zmq depends on pyzmq >= 2.1.4.
 
 Dependencies for the IPython QT console
 =======================================
 
 pyzmq
 -----
 
 Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and
 PyZMQ.
 
 Qt
 --
 
 Also with 0.11, a new GUI was added using the work in :mod:`IPython.zmq`, which
 can be launched with ``ipython qtconsole``. The GUI is built on Qt, and works
 with either PyQt, which can be installed from the `PyQt website
 <http://www.riverbankcomputing.co.uk/>`_, or `PySide
 <http://www.pyside.org/>`_, from Nokia.
 
 pygments
 --------
 
 The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_
 project, which is easy_install-able.
 
 .. _installnotebook:
 
 Dependencies for the IPython HTML notebook
 ==========================================
 
 The IPython notebook is a notebook-style web interface to IPython and can be
 started withe command ``ipython notebook``.
 
 pyzmq
 -----
 
 Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console`
 packages, the HTML notebook requires ZeroMQ and PyZMQ.
 
 Tornado
 -------
 
 The IPython notebook uses the Tornado_ project for its HTTP server.  Tornado 2.1
 is required, in order to support current versions of browsers, due to an update
 to the websocket protocol.
 
 
 MathJax
 -------
 
 The IPython notebook uses the MathJax_ Javascript library for rendering LaTeX
 in web browsers. Because MathJax is large, we don't include it with
 IPython. Normally IPython will load MathJax from a CDN, but if you have a slow
 network connection, or want to use LaTeX without an internet connection at all,
 you can install MathJax locally.
 
 A quick and easy method is to install it from a python session::
 
     from IPython.external.mathjax import install_mathjax
     install_mathjax()
 
 If you need tighter configuration control, you can download your own copy
 of MathJax from http://www.mathjax.org/download/ - use the MathJax-1.1 link.
 When you have the file stored locally, install it with::
 
 	python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v1.1-0-g5a7e4d7.zip
 
 For unusual needs, IPython can tell you what directory it wants to find MathJax in::
 
 	python -m IPython.external.mathjax -d
 
-All of these options require write access to the IPython install directory, so if
-you have a system-wide Python install, it may need to be done with ``sudo``.
+By default Mathjax will be installed in your ipython profile directory, but you
+can make system wide install, please refere to the documentation and helper function 
+of IPython.external.mathjax
 
 Browser Compatibility
 ---------------------
 
 The notebook uses WebSockets and the flexible box model. These features are
 available in the following browsers:
 
 * Chrome
 * Safari
 * Firefox 6 and above
 * Firefox 4 and 5: These browsers have WebSocket support, but it is disabled by
   default. If you're unable to upgrade, you can enable it by entering ``about:config``
   in the URL bar and then setting ``network.websocket.enabled`` and
   ``network.websocket.override-security-block`` to ``true``.
 
 Internet Explorer 9 does not support WebSockets or the flexible box model, but
 these features should appear in Internet Explorer 10.
 
 
 .. _ZeroMQ: http://www.zeromq.org
 .. _PyZMQ: https://github.com/zeromq/pyzmq
 .. _paramiko: https://github.com/robey/paramiko
 .. _pygments: http://pygments.org
 .. _pexpect: http://www.noah.org/wiki/Pexpect
 .. _Tornado: http://www.tornadoweb.org
 .. _MathJax: http://www.mathjax.org