From 7cbac8c0ec534e5499ebb2a0658b367db5c9cb0c 2008-10-04 05:37:23 From: Fernando Perez Date: 2008-10-04 05:37:23 Subject: [PATCH] Documentation updates. - Add info about the development workflow and Launchpad, major edits to various docs. - As I went, updated various files to remove hard tabs, update source listings to bash highlighting, etc. --- diff --git a/docs/source/development/development.txt b/docs/source/development/development.txt index 5bd03d5..ae0523a 100644 --- a/docs/source/development/development.txt +++ b/docs/source/development/development.txt @@ -8,18 +8,16 @@ IPython development guidelines Overview ======== -IPython is the next generation of IPython. It is named such for two reasons: - -- Eventually, IPython will become IPython version 1.0. -- This new code base needs to be able to co-exist with the existing IPython until - it is a full replacement for it. Thus we needed a different name. We couldn't - use ``ipython`` (lowercase) as some files systems are case insensitive. - -There are two, no three, main goals of the IPython effort: +Currently, IPython's development tree contains all of the code that used to be +part of IPython since the project's inception in 2001, plus all of the effort +that was known for a while (roughly 2004-2008) as `IPython1'. The IPyhton1 +development was meant to be an effort to: 1. Clean up the existing codebase and write lots of tests. -2. Separate the core functionality of IPython from the terminal to enable IPython - to be used from within a variety of GUI applications. + +2. Separate the core functionality of IPython from the terminal to enable + IPython to be used from within a variety of GUI applications. + 3. Implement a system for interactive parallel computing. While the third goal may seem a bit unrelated to the main focus of IPython, it @@ -56,6 +54,7 @@ subpackages will have its own: - **Scripts**. Each subpackage should have its own ``scripts`` subdirectory that contains all of the command line scripts associated with the subpackage. + Installation and dependencies ----------------------------- @@ -127,116 +126,140 @@ Specific subpackages Version control =============== -In the past, IPython development has been done using `Subversion`__. Recently, -we made the transition to using `Bazaar`__ and `Launchpad`__. This makes it -much easier for people to contribute code to IPython. Here is a sketch of how -to use Bazaar for IPython development. First, you should install Bazaar. -After you have done that, make sure that it is working by getting the latest -main branch of IPython:: +All IPython development today is done using the `Bazaar`__ system for +distributed version control and the `Launchpad`__ site for code hosting and bug +tracking. This makes it very easy for anyone to contribute code to IPython. - $ bzr branch lp:ipython +.. __: http://bazaar-vcs.org +.. __: http://launchpad.net/ipython -Now you can create a new branch for you to do your work in:: +If you are interested in contributing to IPython, you should familiarize a bit +with how to use bazaar, but this document gives you a concise set of steps to +get started. If you are going to become heavily involved with creating code +for IPython you'll eventually want to have a Launchpad account (free) so you +can publish your own code on the site for review and merging, but small +contributions can be simply sent via email to the IPython list as patches. - $ bzr branch ipython ipython-mybranch +Start by creating what Bazaar calls a `shared repository`_: -The typical work cycle in this branch will be to make changes in -``ipython-mybranch`` and then commit those changes using the commit command:: +.. sourcecode:: bash - $ ...do work in ipython-mybranch... - $ bzr ci -m "the commit message goes here" + # You can choose any name you want instead of "ipython-repo" + bzr init-repo ipython-repo -Please note that since we now don't use an old-style linear ChangeLog (that -tends to cause problems with distributed version control systems), you should -ensure that your log messages are reasonably detailed. Use a docstring-like -approach in the commit messages (including the second line being left -*blank*):: +.. _shared repository: http://bazaar-vcs.org/SharedRepositoryTutorial - Single line summary of changes being committed. +This creates an empty repository where a lot of related branches can be kept, +and they all reuse common storage. This way, many operations are very fast and +take up less space. Now, go to the newly created repository and make a local +branch of the public trunk: - - more details when warranted ... - - including crediting outside contributors if they sent the - code/bug/idea! +.. sourcecode:: bash -If we couple this with a policy of making single commits for each reasonably -atomic change, the bzr log should give an excellent view of the project, and -the `--short` log option becomes a nice summary. + cd ipython-repo + # This makes a local copy of the public trunk called "trunk-lp" + bzr branch lp:ipython trunk-lp + +The ``trunk-lp`` branch is meant to always be a pristine copy of the public +trunk. From here, make a personal development copy of the public trunk, where +you'll make your changes: + +.. sourcecode:: bash -While working with this branch, it is a good idea to merge in changes that have -been made upstream in the parent branch. This can be done by doing:: + bzr branch trunk-lp trunk-dev - $ bzr pull +Now, your working area looks like this:: -If this command shows that the branches have diverged, then you should do a -merge instead:: + maqroll[ipython-repo]> ls -a + ./ ../ .bzr/ trunk-dev/ trunk-lp/ + +The ``.bzr`` directory is the Bazaar storage area, and you now have both the +reference copy of the public trunk and one working copy for your own +development. You can later make further branches as needed (a common workflow +is to make branches to contain specific feature implementations until they are +ready to be merged). + +The typical work cycle will be to make changes in ``trunk-dev`` and then commit +those changes as often as needed: - $ bzr merge lp:ipython +.. sourcecode:: bash -If you want others to be able to see your branch, you can create an account -with launchpad and push the branch to your own workspace:: + cd trunk-dev + # ... implement cool new feature... + bzr commit -m "Commit message goes here." - $ bzr push bzr+ssh://@bazaar.launchpad.net/~/+junk/ipython-mybranch +Please note that since we now don't use an old-style linear ChangeLog (that +tends to cause problems with distributed version control systems), you should +ensure that your log messages are reasonably detailed. For non-trivial +changes, use a docstring-like approach in the commit messages (including the +second line being left *blank*). Type ``bzr commit`` *without* the ``-m`` +switch, and Bazaar will open an editor where you can type a more detailed +message:: -Finally, once the work in your branch is done, you can merge your changes back -into the `ipython` branch by using merge:: + Single line summary of changes being committed. - $ cd ipython - $ merge ../ipython-mybranch - [resolve any conflicts] - $ bzr ci -m "Fixing that bug" - $ bzr push + - more details when warranted ... + - including crediting outside contributors if they sent the + code/bug/idea! -But this will require you to have write permissions to the `ipython` branch. -It you don't you can tell one of the IPython devs about your branch and they -can do the merge for you. +If we couple this with a policy of making single commits for each reasonably +atomic change, the bzr log should give an excellent view of the project, and +the ``--short`` log option becomes a nice summary. -More information about Bazaar workflows can be found `here`__. +As you work on the branch, it's a good idea to frequently keep your copy of the +trunk updated with respect to Launchpad. This is done via: -.. __: http://subversion.tigris.org/ -.. __: http://bazaar-vcs.org/ -.. __: http://www.launchpad.net/ipython -.. __: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html +.. sourcecode:: bash -Documentation -============= + cd trunk-lp + bzr pull -Standalone documentation ------------------------- +Bazaar can then merge any changes that were done to the public trunk into your +local branch via: -All standalone documentation should be written in plain text (``.txt``) files -using `reStructuredText`_ for markup and formatting. All such documentation -should be placed in the top level directory ``docs`` of the IPython source -tree. Or, when appropriate, a suitably named subdirectory should be used. The -documentation in this location will serve as the main source for IPython -documentation and all existing documentation should be converted to this -format. +.. sourcecode:: bash -In the future, the text files in the ``docs`` directory will be used to -generate all forms of documentation for IPython. This include documentation on -the IPython website as well as *pdf* documentation. + cd trunk-dev + bzr merge ../trunk-lp + bzr commit -m"Merged upstream changes" -.. _reStructuredText: http://docutils.sourceforge.net/rst.html +This workflow ensures that a local copy stays in sync with the public trunk, +while allowing for local development to be pushed back for public review. -Docstring format ----------------- +Once your changes are ready for review, you can push them to Launchpad where +the IPython team can review them and give you feedback. The first time, use: -Good docstrings are very important. All new code will use `Epydoc`_ for -generating API docs, so we will follow the `Epydoc`_ conventions. More -specifically, we will use `reStructuredText`_ for markup and formatting, since -it is understood by a wide variety of tools. This means that if in the future -we have any reason to change from `Epydoc`_ to something else, we'll have fewer -transition pains. +.. sourcecode:: bash -Details about using `reStructuredText`_ for docstrings can be found `here -`_. + bzr push --remember bzr+ssh://@bazaar.launchpad.net/~/ipython/trunk-dev -.. _Epydoc: http://epydoc.sourceforge.net/ +where ```` is your Launchpad user name. This will make this branch +publicly visible to all. In subsequent uses you can simply run in the branch: -Additional PEPs of interest regarding documentation of code: +.. sourcecode:: bash -- `Docstring Conventions `_ -- `Docstring Processing System Framework `_ -- `Docutils Design Specification `_ + bzr push + +.. note:: + + Before you can push your code to Launchpad, you need to configure your SSH + keys. You can do this by clicking on ``Change details`` for your profile + and then clicking on the ``SSH Keys`` tab. This should take you to a URL + of the form ``https://launchpad.net/~/+editsshkeys`` with instructions + on how to upload your keys. + +Once the branch is publicly visible, using the launchpad interface it can be +marked for merging with the link ``Propose for merging into another branch``, +leaving the default choice of trunk as its target. This way, Launchpad tracks +what changes of this branch are new with respect to the trunk, others in the +team can review it, and merge the changes into the trunk. + +The IPython team has a policy of reviewing all code (both from core members of +the team and from external contributors) before merging it. Code should be +clearly documented (as explained further in this guide), clear and well tested. +We will be happy to provide you with feedback for your code to be a great +contribution to the project, and we've found that peer review of code is an +excellent way to improve the quality of everyone's work. Coding conventions @@ -318,6 +341,86 @@ the code, but in general we should remove as many unnecessary ``IP``/``ip`` prefixes as possible. However, if a prefix seems absolutely necessary the more specific ``IPY`` or ``ipy`` are preferred. + +Documentation +============= + +Standalone documentation +------------------------ + +All standalone documentation should be written in plain text (``.txt``) files +using `reStructuredText`_ for markup and formatting. All such documentation +should be placed in the top level directory ``docs`` of the IPython source +tree. Or, when appropriate, a suitably named subdirectory should be used. The +documentation in this location will serve as the main source for IPython +documentation and all existing documentation should be converted to this +format. + +In the future, the text files in the ``docs`` directory will be used to +generate all forms of documentation for IPython. This include documentation on +the IPython website as well as *pdf* documentation. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html + +A bit of shell code: + +.. sourcecode:: bash + + cd /tmp + echo "My home directory is: $HOME" + ls + +A bit of Python code: + +.. sourcecode:: python + + for i in range(10): + print i, + print "A big number:",2**34 + +An interactive Python session: + +.. sourcecode:: python + + >>> from IPython import genutils + >>> genutils.get_ipython_dir() + '/home/fperez/.ipython' + + +An IPython session: + +.. sourcecode:: ipython + + In [8]: import IPython + + In [9]: print "This IPython is version:",IPython.__version__ + This IPython is version: 0.9.1 + + + +Docstring format +---------------- + +Good docstrings are very important. All new code will use `Epydoc`_ for +generating API docs, so we will follow the `Epydoc`_ conventions. More +specifically, we will use `reStructuredText`_ for markup and formatting, since +it is understood by a wide variety of tools. This means that if in the future +we have any reason to change from `Epydoc`_ to something else, we'll have fewer +transition pains. + +Details about using `reStructuredText`_ for docstrings can be found `here +`_. + +.. _Epydoc: http://epydoc.sourceforge.net/ + +Additional PEPs of interest regarding documentation of code: + +- `Docstring Conventions `_ +- `Docstring Processing System Framework `_ +- `Docutils Design Specification `_ + + + .. _devel_testing: Testing system diff --git a/docs/source/install/index.txt b/docs/source/install/index.txt index 6ddc5b0..f6cd618 100644 --- a/docs/source/install/index.txt +++ b/docs/source/install/index.txt @@ -1,8 +1,8 @@ .. _install_index: -================== +============ Installation -================== +============ .. toctree:: :maxdepth: 2 diff --git a/docs/source/install/install.txt b/docs/source/install/install.txt index 4388cc2..e3e5361 100644 --- a/docs/source/install/install.txt +++ b/docs/source/install/install.txt @@ -1,45 +1,90 @@ 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. +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. IPython requires Python version 2.4 or greater. We have not tested -IPython with the upcoming 2.6 or 3.0 versions. +dependencies. IPython requires Python version 2.4 or greater. We have not +tested IPython with the upcoming 2.6 or 3.0 versions, though preliminary +reports of 2.6 usage are encouraging. 3.0 porting will take longer, however. .. warning:: - IPython will not work with Python 2.3 or below. + IPython will not work with Python 2.3 or below. -Some of the installation approaches use the :mod:`setuptools` package and its :command:`easy_install` command line program. In many scenarios, this provides the most simple method of installing IPython and its dependencies. It is not required though. More information about :mod:`setuptools` can be found on its website. +Some of the installation approaches use the :mod:`setuptools` package and its +:command:`easy_install` command line program. In many scenarios, this provides +the most simple method of installing IPython and its dependencies. It is not +required though. More information about :mod:`setuptools` can be found on its +website. + +More general information about installing Python packages can be found in +Python's documentation at http://www.python.org/doc/. -More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/. 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. See below for details of how to make sure you have a working :mod:`readline`. +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. See below for details of how to make sure you have a working +:mod:`readline`. Installation using easy_install ------------------------------- -If you have :mod:`setuptools` installed, the easiest way of getting IPython is to simple use :command:`easy_install`:: +If you have :mod:`setuptools` installed, the easiest way of getting IPython is +to use :command:`easy_install`: + +.. sourcecode:: bash + + easy_install IPython + +Unless you've written a custom distutils script as explained here_, that will +try to install either in a default system-wide location, which may require +administrator access. If that is the case, you can either run the command with +root privileges: + +.. sourcecode:: bash + + sudo easy_install IPython + +or you can specify an alternate location, for example: - $ easy_install IPython +.. sourcecode:: bash + + easy_install --prefix=~/usr/local IPython + +where this assumes that ``~/usr/local`` is a valid prefix for you to install +packages to in your user account. + +.. _here: http://docs.python.org/install/index.html#inst-config-files -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 `_. Then do the following:: +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 +`_. Then do the following (using the +appropriate version number): - $ tar -xzf ipython.tar.gz - $ cd ipython - $ python setup.py install +.. sourcecode:: bash -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`. + 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 ------- @@ -55,22 +100,31 @@ There are a few caveats for Windows users. The main issue is that a basic ``pyt Installing the development version ---------------------------------- -It is also possible to install the development version of IPython from our `Bazaar `_ source code -repository. To do this you will need to have Bazaar installed on your system. Then just do:: +It is also possible to install the development version of IPython from our +`Bazaar `_ source code repository. To do this you will +need to have Bazaar installed on your system. Then just do:: + + .. sourcecode:: bash - $ bzr branch lp:ipython - $ cd ipython - $ python setup.py install + bzr branch lp:ipython + cd ipython + python setup.py install Again, this last step on Windows won't create ``.bat`` files or Start Menu shortcuts, so you will have to use one of the other approaches listed above. -Some users want to be able to follow the development branch as it changes. If you have :mod:`setuptools` installed, this is easy. Simply replace the last step by:: +Some users want to be able to follow the development branch as it changes. If +you have :mod:`setuptools` installed, this is easy. Simply replace the last +step by: + +.. sourcecode:: bash - $ python setupegg.py develop + 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:: +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: - $ bzr pull +.. sourcecode:: bash + + bzr pull Basic optional dependencies =========================== @@ -92,11 +146,18 @@ In principle, all Python distributions should come with a working :mod:`readline * If you are running Windows, which doesn't have a :mod:`readline` module. -On OS X, the built-in Python doesn't not have :mod:`readline` because of license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, many of the issues related to the differences between readline and libedit have been resolved. For many users, libedit may be sufficient. +On OS X, the built-in Python doesn't not have :mod:`readline` because of +license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has +a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, +many of the issues related to the differences between readline and libedit have +been resolved. For many users, libedit may be sufficient. + +Most users on OS X will want to get the full :mod:`readline` module. To get a +working :mod:`readline` module, just do (with :mod:`setuptools` installed): -Most users on OS X will want to get the full :mod:`readline` module. To get a working :mod:`readline` module, just do (with :mod:`setuptools` installed):: +.. sourcecode:: bash - $ easy_install readline + easy_install readline .. note: @@ -104,83 +165,126 @@ Most users on OS X will want to get the full :mod:`readline` module. To get a w official python.org binaries) already have readline installed so you don't have to do this step. -If needed, the readline egg can be build and installed from source (see the wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard). +If needed, the readline egg can be build and installed from source (see the +wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard). -On Windows, you will need the PyReadline module. 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 `_. The :mod:`ctypes` module, which comes with Python 2.5 and greater, is required by PyReadline. It is available for Python 2.4 at http://python.net/crew/theller/ctypes. +On Windows, you will need the PyReadline module. 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 `_. The +:mod:`ctypes` module, which comes with Python 2.5 and greater, is required by +PyReadline. It is available for Python 2.4 at +http://python.net/crew/theller/ctypes. 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`:: +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`: + +.. sourcecode:: bash - $ easy_install nose + easy_install nose -Another way of getting this is to do:: +Another way of getting this is to do: - $ easy_install IPython[test] +.. sourcecode:: bash -For more installation options, see the `nose website `_. Once you have nose installed, you can run IPython's test suite using the iptest command:: + easy_install IPython[test] - $ iptest +For more installation options, see the `nose website +`_. Once you have nose +installed, you can run IPython's test suite using the iptest command: + +.. sourcecode:: bash + + iptest pexpect ------- -The `pexpect `_ package is used in IPython's :command:`irunner` script. On Unix platforms (including OS X), just do:: +The `pexpect `_ package is used in IPython's +:command:`irunner` script. On Unix platforms (including OS X), just do: + +.. sourcecode:: bash - $ easy_install pexpect + easy_install pexpect Windows users are out of luck as pexpect does not run there. Dependencies for IPython.kernel (parallel computing) ==================================================== -The IPython kernel provides a nice architecture for parallel computing. The main focus of this architecture is on interactive parallel computing. These features require a number of additional packages: +The IPython kernel provides a nice architecture for parallel computing. The +main focus of this architecture is on interactive parallel computing. These +features require a number of additional packages: * zope.interface (yep, we use interfaces) * Twisted (asynchronous networking framework) * Foolscap (a nice, secure network protocol) * pyOpenSSL (security for network connections) -On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do:: +On a Unix style platform (including OS X), if you want to use +:mod:`setuptools`, you can just do: - $ easy_install IPython[kernel] # the first three - $ easy_install IPython[security] # pyOpenSSL +.. sourcecode:: bash + + easy_install IPython[kernel] # the first three + easy_install IPython[security] # pyOpenSSL zope.interface and Twisted -------------------------- -On Unix style platforms (including OS X), the simplest way of getting the these is to use :command:`easy_install`:: +On Unix style platforms (including OS X), the simplest way of getting the these +is to use :command:`easy_install`: + +.. sourcecode:: bash - $ easy_install zope.interface - $ easy_install Twisted + easy_install zope.interface + easy_install Twisted -Of course, you can also download the source tarballs from the `Twisted website `_ and the `zope.interface page at PyPI `_ and do the usual ``python setup.py install`` if you prefer. +Of course, you can also download the source tarballs from the `Twisted website +`_ and the `zope.interface page at PyPI +`_ and do the usual ``python +setup.py install`` if you prefer. -Windows is a bit different. For zope.interface and Twisted, simply get the latest binary ``.exe`` installer from the Twisted website. This installer includes both zope.interface and Twisted and should just work. +Windows is a bit different. For zope.interface and Twisted, simply get the +latest binary ``.exe`` installer from the Twisted website. This installer +includes both zope.interface and Twisted and should just work. Foolscap -------- -Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features. +Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to +implement our parallel computing features. + +On all platforms a simple: -On all platforms a simple:: +.. sourcecode:: bash - $ easy_install foolscap + easy_install foolscap -should work. You can also download the source tarballs from the `Foolscap website `_ and do ``python setup.py install`` if you prefer. +should work. You can also download the source tarballs from the `Foolscap +website `_ and do ``python setup.py install`` +if you prefer. pyOpenSSL --------- -IPython requires an older version of pyOpenSSL (0.6 rather than the current 0.7). There are a couple of options for getting this: +IPython requires an older version of pyOpenSSL (0.6 rather than the current +0.7). There are a couple of options for getting this: + +1. Most Linux distributions have packages for pyOpenSSL. + +2. The built-in Python 2.5 on OS X 10.5 already has it installed. + +3. There are source tarballs on the pyOpenSSL website. On Unix-like + platforms, these can be built using ``python seutp.py install``. -1. Most Linux distributions have packages for pyOpenSSL. -2. The built-in Python 2.5 on OS X 10.5 already has it installed. -3. There are source tarballs on the pyOpenSSL website. On Unix-like - platforms, these can be built using ``python seutp.py install``. -4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website `_. +4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website + `_. Dependencies for IPython.frontend (the IPython GUI) =================================================== @@ -188,4 +292,9 @@ Dependencies for IPython.frontend (the IPython GUI) wxPython -------- -Starting with IPython 0.9, IPython has a new IPython.frontend package that has a nice wxPython based IPython GUI. As you would expect, this GUI requires wxPython. Most Linux distributions have wxPython packages available and the built-in Python on OS X comes with wxPython preinstalled. For Windows, a binary installer is available on the `wxPython website `_. \ No newline at end of file +Starting with IPython 0.9, IPython has a new IPython.frontend package that has +a nice wxPython based IPython GUI. As you would expect, this GUI requires +wxPython. Most Linux distributions have wxPython packages available and the +built-in Python on OS X comes with wxPython preinstalled. For Windows, a +binary installer is available on the `wxPython website +`_. \ No newline at end of file diff --git a/docs/source/overview.txt b/docs/source/overview.txt index 9ee38cb..184a0ea 100644 --- a/docs/source/overview.txt +++ b/docs/source/overview.txt @@ -91,10 +91,10 @@ Main features of the interactive shell IPython has an internal job manager called jobs, and a convenience backgrounding magic function called :samp:`%bg`. -* The ability to expand python variables when calling the system - shell. In a shell command, any python variable prefixed with :samp:`$` is - expanded. A double :samp:`$$` allows passing a literal :samp:`$` to the shell (for - access to shell and environment variables like :envvar:`PATH`). +* The ability to expand python variables when calling the system shell. In a + shell command, any python variable prefixed with :samp:`$` is expanded. A + double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access + to shell and environment variables like :envvar:`PATH`). * Filesystem navigation, via a magic :samp:`%cd` command, along with a persistent bookmark system (using :samp:`%bookmark`) for fast access to @@ -150,17 +150,16 @@ Main features of the interactive shell about the local namespaces (very useful in debugging and data analysis situations). -* Easy debugger access. You can set IPython to call up an enhanced - version of the Python debugger (pdb) every time there is an - uncaught exception. This drops you inside the code which triggered - the exception with all the data live and it is possible to - navigate the stack to rapidly isolate the source of a bug. The - :samp:`%run` magic command (with the :samp:`-d` option) can run any script under - pdb's control, automatically setting initial breakpoints for you. - This version of pdb has IPython-specific improvements, including - tab-completion and traceback coloring support. For even easier - debugger access, try :samp:`%debug` after seeing an exception. winpdb is - also supported, see ipy_winpdb extension. +* Easy debugger access. You can set IPython to call up an enhanced version of + the Python debugger (pdb) every time there is an uncaught exception. This + drops you inside the code which triggered the exception with all the data + live and it is possible to navigate the stack to rapidly isolate the source + of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run + any script under pdb's control, automatically setting initial breakpoints for + you. This version of pdb has IPython-specific improvements, including + tab-completion and traceback coloring support. For even easier debugger + access, try :samp:`%debug` after seeing an exception. winpdb is also + supported, see ipy_winpdb extension. * Profiler support. You can run single statements (similar to :samp:`profile.run()`) or complete programs under the profiler's control. @@ -176,10 +175,11 @@ Main features of the interactive shell Interactive parallel computing ============================== -Increasingly, parallel computer hardware, such as multicore CPUs, clusters and supercomputers, is becoming ubiquitous. Over the last 3 years, we have developed an -architecture within IPython that allows such hardware to be used quickly and easily -from Python. Moreover, this architecture is designed to support interactive and -collaborative parallel computing. +Increasingly, parallel computer hardware, such as multicore CPUs, clusters and +supercomputers, is becoming ubiquitous. Over the last 3 years, we have +developed an architecture within IPython that allows such hardware to be used +quickly and easily from Python. Moreover, this architecture is designed to +support interactive and collaborative parallel computing. The main features of this system are: @@ -204,16 +204,16 @@ The main features of this system are: * Capabilities based security model with full encryption of network connections. -* Share live parallel jobs with other users securely. We call this collaborative - parallel computing. +* Share live parallel jobs with other users securely. We call this + collaborative parallel computing. * Dynamically load balanced task farming system. * Robust error handling. Python exceptions raised in parallel execution are gathered and presented to the top-level code. -For more information, see our :ref:`overview ` of using IPython for -parallel computing. +For more information, see our :ref:`overview ` of using IPython +for parallel computing. Portability and Python requirements ----------------------------------- @@ -225,8 +225,7 @@ work with some minor changes. IPython is known to work on the following operating systems: * Linux - * AIX - * Most other Unix-like OSs (Solaris, BSD, etc.) + * Most other Unix-like OSs (AIX, Solaris, BSD, etc.) * Mac OS X * Windows (CygWin, XP, Vista, etc.) diff --git a/docs/source/parallel/index.txt b/docs/source/parallel/index.txt index 15c8436..76f19e1 100644 --- a/docs/source/parallel/index.txt +++ b/docs/source/parallel/index.txt @@ -11,4 +11,4 @@ Using IPython for parallel computing parallel_multiengine.txt parallel_task.txt parallel_mpi.txt - + visionhpc.txt diff --git a/tools/compile.py b/tools/compile.py old mode 100644 new mode 100755