From d0ce4479a0a2ecbd1ad00b9e20539226e61f77f0 2008-06-10 21:57:41 From: Brian E Granger Date: 2008-06-10 21:57:41 Subject: [PATCH] More moving around doc files. --- diff --git a/docs/source/changes/index.txt b/docs/source/changes/index.txt new file mode 100644 index 0000000..c89bba0 --- /dev/null +++ b/docs/source/changes/index.txt @@ -0,0 +1,7 @@ +What's new in IPython +===================== + +.. toctree:: + :maxdepth: 1 + + changes.txt diff --git a/docs/source/core/index.txt b/docs/source/core/index.txt deleted file mode 100644 index 51d55c9..0000000 --- a/docs/source/core/index.txt +++ /dev/null @@ -1,7 +0,0 @@ -IPython Documentation -===================== - -.. toctree:: - :maxdepth: 2 - - ipython.txt \ No newline at end of file diff --git a/docs/source/parallel/faq.txt b/docs/source/faq.txt similarity index 100% rename from docs/source/parallel/faq.txt rename to docs/source/faq.txt diff --git a/docs/source/history.txt b/docs/source/history.txt index e69de29..57860ba 100644 --- a/docs/source/history.txt +++ b/docs/source/history.txt @@ -0,0 +1,3 @@ +====================== +The History of IPython +====================== diff --git a/docs/source/parallel/install.txt b/docs/source/install/advanced.txt similarity index 96% rename from docs/source/parallel/install.txt rename to docs/source/install/advanced.txt index 690ee45..149e240 100644 --- a/docs/source/parallel/install.txt +++ b/docs/source/install/advanced.txt @@ -1,3 +1,7 @@ +========================================= +Advanced installation options for IPython +========================================= + .. _install: =================== diff --git a/docs/source/install/basic.txt b/docs/source/install/basic.txt new file mode 100644 index 0000000..fbf2f3a --- /dev/null +++ b/docs/source/install/basic.txt @@ -0,0 +1,272 @@ +============================= +Basic installation of IPython +============================= + +Installation +============ + +Instant instructions +-------------------- + +If you are of the impatient kind, under Linux/Unix simply untar/unzip +the download, then install with 'python setup.py install'. Under +Windows, double-click on the provided .exe binary installer. + +Then, take a look at Customization_ section for configuring things +optimally and `Quick tips`_ for quick tips on efficient use of +IPython. You can later refer to the rest of the manual for all the +gory details. + +See the notes in upgrading_ section for upgrading IPython versions. + + + Detailed Unix instructions (Linux, Mac OS X, etc.) + +For RPM based systems, simply install the supplied package in the usual +manner. If you download the tar archive, the process is: + + 1. Unzip/untar the ipython-XXX.tar.gz file wherever you want (XXX is + the version number). It will make a directory called ipython-XXX. + Change into that directory where you will find the files README + and setup.py. Once you've completed the installation, you can + safely remove this directory. + 2. If you are installing over a previous installation of version + 0.2.0 or earlier, first remove your $HOME/.ipython directory, + since the configuration file format has changed somewhat (the '=' + were removed from all option specifications). Or you can call + ipython with the -upgrade option and it will do this automatically + for you. + 3. IPython uses distutils, so you can install it by simply typing at + the system prompt (don't type the $):: + + $ python setup.py install + + Note that this assumes you have root access to your machine. If + you don't have root access or don't want IPython to go in the + default python directories, you'll need to use the ``--home`` option + (or ``--prefix``). For example:: + + $ python setup.py install --home $HOME/local + + will install IPython into $HOME/local and its subdirectories + (creating them if necessary). + You can type:: + + $ python setup.py --help + + for more details. + + Note that if you change the default location for ``--home`` at + installation, IPython may end up installed at a location which is + not part of your $PYTHONPATH environment variable. In this case, + you'll need to configure this variable to include the actual + directory where the IPython/ directory ended (typically the value + you give to ``--home`` plus /lib/python). + + +Mac OSX information +------------------- + +Under OSX, there is a choice you need to make. Apple ships its own build +of Python, which lives in the core OSX filesystem hierarchy. You can +also manually install a separate Python, either purely by hand +(typically in /usr/local) or by using Fink, which puts everything under +/sw. Which route to follow is a matter of personal preference, as I've +seen users who favor each of the approaches. Here I will simply list the +known installation issues under OSX, along with their solutions. + +This page: http://geosci.uchicago.edu/~tobis/pylab.html contains +information on this topic, with additional details on how to make +IPython and matplotlib play nicely under OSX. + +To run IPython and readline on OSX "Leopard" system python, see the +wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard + + +GUI problems +------------ + +The following instructions apply to an install of IPython under OSX from +unpacking the .tar.gz distribution and installing it for the default +Python interpreter shipped by Apple. If you are using a fink install, +fink will take care of these details for you, by installing IPython +against fink's Python. + +IPython offers various forms of support for interacting with graphical +applications from the command line, from simple Tk apps (which are in +principle always supported by Python) to interactive control of WX, Qt +and GTK apps. Under OSX, however, this requires that ipython is +installed by calling the special pythonw script at installation time, +which takes care of coordinating things with Apple's graphical environment. + +So when installing under OSX, it is best to use the following command:: + + $ sudo pythonw setup.py install --install-scripts=/usr/local/bin + +or + + $ sudo pythonw setup.py install --install-scripts=/usr/bin + +depending on where you like to keep hand-installed executables. + +The resulting script will have an appropriate shebang line (the first +line in the script whic begins with #!...) such that the ipython +interpreter can interact with the OS X GUI. If the installed version +does not work and has a shebang line that points to, for example, just +/usr/bin/python, then you might have a stale, cached version in your +build/scripts- directory. Delete that directory and +rerun the setup.py. + +It is also a good idea to use the special flag ``--install-scripts`` as +indicated above, to ensure that the ipython scripts end up in a location +which is part of your $PATH. Otherwise Apple's Python will put the +scripts in an internal directory not available by default at the command +line (if you use /usr/local/bin, you need to make sure this is in your +$PATH, which may not be true by default). + + +Readline problems +----------------- + +By default, the Python version shipped by Apple does not include the +readline library, so central to IPython's behavior. If you install +IPython against Apple's Python, you will not have arrow keys, tab +completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt +readline library here: +http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip + +If you are using OSX 10.4 (Tiger), after installing this package you +need to either: + + 1. move readline.so from /Library/Python/2.3 to + /Library/Python/2.3/site-packages, or + 2. install http://pythonmac.org/packages/TigerPython23Compat.pkg.zip + +Users installing against Fink's Python or a properly hand-built one +should not have this problem. + + +DarwinPorts +----------- + +I report here a message from an OSX user, who suggests an alternative +means of using IPython under this operating system with good results. +Please let me know of any updates that may be useful for this section. +His message is reproduced verbatim below: + + From: Markus Banfi + + As a MacOS X (10.4.2) user I prefer to install software using + DawinPorts instead of Fink. I had no problems installing ipython + with DarwinPorts. It's just: + + sudo port install py-ipython + + It automatically resolved all dependencies (python24, readline, + py-readline). So far I did not encounter any problems with the + DarwinPorts port of ipython. + + + +Windows instructions +-------------------- + +Some of IPython's very useful features are: + + * Integrated readline support (Tab-based file, object and attribute + completion, input history across sessions, editable command line, + etc.) + * Coloring of prompts, code and tracebacks. + +.. _pyreadline: + +These, by default, are only available under Unix-like operating systems. +However, thanks to Gary Bishop's work, Windows XP/2k users can also +benefit from them. His readline library originally implemented both GNU +readline functionality and color support, so that IPython under Windows +XP/2k can be as friendly and powerful as under Unix-like environments. + +This library, now named PyReadline, has been absorbed by the IPython +team (Jörgen Stenarson, in particular), and it continues to be developed +with new features, as well as being distributed directly from the +IPython site. + +The PyReadline extension requires CTypes and the windows IPython +installer needs PyWin32, so in all you need: + + 1. PyWin32 from http://sourceforge.net/projects/pywin32. + 2. PyReadline for Windows from + http://ipython.scipy.org/moin/PyReadline/Intro. That page contains + further details on using and configuring the system to your liking. + 3. Finally, only if you are using Python 2.3 or 2.4, you need CTypes + from http://starship.python.net/crew/theller/ctypes(you must use + version 0.9.1 or newer). This package is included in Python 2.5, + so you don't need to manually get it if your Python version is 2.5 + or newer. + +Warning about a broken readline-like library: several users have +reported problems stemming from using the pseudo-readline library at +http://newcenturycomputers.net/projects/readline.html. This is a broken +library which, while called readline, only implements an incomplete +subset of the readline API. Since it is still called readline, it fools +IPython's detection mechanisms and causes unpredictable crashes later. +If you wish to use IPython under Windows, you must NOT use this library, +which for all purposes is (at least as of version 1.6) terminally broken. + + +Installation procedure +---------------------- + +Once you have the above installed, from the IPython download directory +grab the ipython-XXX.win32.exe file, where XXX represents the version +number. This is a regular windows executable installer, which you can +simply double-click to install. It will add an entry for IPython to your +Start Menu, as well as registering IPython in the Windows list of +applications, so you can later uninstall it from the Control Panel. + +IPython tries to install the configuration information in a directory +named .ipython (_ipython under Windows) located in your 'home' +directory. IPython sets this directory by looking for a HOME environment +variable; if such a variable does not exist, it uses HOMEDRIVE\HOMEPATH +(these are always defined by Windows). This typically gives something +like C:\Documents and Settings\YourUserName, but your local details may +vary. In this directory you will find all the files that configure +IPython's defaults, and you can put there your profiles and extensions. +This directory is automatically added by IPython to sys.path, so +anything you place there can be found by import statements. + + +Upgrading +--------- + +For an IPython upgrade, you should first uninstall the previous version. +This will ensure that all files and directories (such as the +documentation) which carry embedded version strings in their names are +properly removed. + + +Manual installation under Win32 +------------------------------- + +In case the automatic installer does not work for some reason, you can +download the ipython-XXX.tar.gz file, which contains the full IPython +source distribution (the popular WinZip can read .tar.gz files). After +uncompressing the archive, you can install it at a command terminal just +like any other Python module, by using 'python setup.py install'. + +After the installation, run the supplied win32_manual_post_install.py +script, which creates the necessary Start Menu shortcuts for you. + + +.. upgrading: + +Upgrading from a previous version +--------------------------------- + +If you are upgrading from a previous version of IPython, you may want +to upgrade the contents of your ~/.ipython directory. Just run +%upgrade, look at the diffs and delete the suggested files manually, +if you think you can lose the old versions. %upgrade will never +overwrite or delete anything. + + diff --git a/docs/source/install/index.txt b/docs/source/install/index.txt index c6df8ac..f19983d 100644 --- a/docs/source/install/index.txt +++ b/docs/source/install/index.txt @@ -7,10 +7,5 @@ User Documentation .. toctree:: :maxdepth: 2 - install.txt - parallel_intro.txt - parallel_multiengine.txt - parallel_task.txt - parallel_mpi.txt - changes.txt - faq.txt + basic.txt + advanced.txt diff --git a/docs/source/interactive/ipython.txt b/docs/source/interactive/ipython.txt index c2f58d6..4a19678 100644 --- a/docs/source/interactive/ipython.txt +++ b/docs/source/interactive/ipython.txt @@ -204,273 +204,6 @@ subversion access, mailing lists and a bug tracking system. I am very grateful to Enthought (http://www.enthought.com) and all of the SciPy team for their contribution. -Installation -============ - -Instant instructions --------------------- - -If you are of the impatient kind, under Linux/Unix simply untar/unzip -the download, then install with 'python setup.py install'. Under -Windows, double-click on the provided .exe binary installer. - -Then, take a look at Customization_ section for configuring things -optimally and `Quick tips`_ for quick tips on efficient use of -IPython. You can later refer to the rest of the manual for all the -gory details. - -See the notes in upgrading_ section for upgrading IPython versions. - - - Detailed Unix instructions (Linux, Mac OS X, etc.) - -For RPM based systems, simply install the supplied package in the usual -manner. If you download the tar archive, the process is: - - 1. Unzip/untar the ipython-XXX.tar.gz file wherever you want (XXX is - the version number). It will make a directory called ipython-XXX. - Change into that directory where you will find the files README - and setup.py. Once you've completed the installation, you can - safely remove this directory. - 2. If you are installing over a previous installation of version - 0.2.0 or earlier, first remove your $HOME/.ipython directory, - since the configuration file format has changed somewhat (the '=' - were removed from all option specifications). Or you can call - ipython with the -upgrade option and it will do this automatically - for you. - 3. IPython uses distutils, so you can install it by simply typing at - the system prompt (don't type the $):: - - $ python setup.py install - - Note that this assumes you have root access to your machine. If - you don't have root access or don't want IPython to go in the - default python directories, you'll need to use the ``--home`` option - (or ``--prefix``). For example:: - - $ python setup.py install --home $HOME/local - - will install IPython into $HOME/local and its subdirectories - (creating them if necessary). - You can type:: - - $ python setup.py --help - - for more details. - - Note that if you change the default location for ``--home`` at - installation, IPython may end up installed at a location which is - not part of your $PYTHONPATH environment variable. In this case, - you'll need to configure this variable to include the actual - directory where the IPython/ directory ended (typically the value - you give to ``--home`` plus /lib/python). - - -Mac OSX information -------------------- - -Under OSX, there is a choice you need to make. Apple ships its own build -of Python, which lives in the core OSX filesystem hierarchy. You can -also manually install a separate Python, either purely by hand -(typically in /usr/local) or by using Fink, which puts everything under -/sw. Which route to follow is a matter of personal preference, as I've -seen users who favor each of the approaches. Here I will simply list the -known installation issues under OSX, along with their solutions. - -This page: http://geosci.uchicago.edu/~tobis/pylab.html contains -information on this topic, with additional details on how to make -IPython and matplotlib play nicely under OSX. - -To run IPython and readline on OSX "Leopard" system python, see the -wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard - - -GUI problems ------------- - -The following instructions apply to an install of IPython under OSX from -unpacking the .tar.gz distribution and installing it for the default -Python interpreter shipped by Apple. If you are using a fink install, -fink will take care of these details for you, by installing IPython -against fink's Python. - -IPython offers various forms of support for interacting with graphical -applications from the command line, from simple Tk apps (which are in -principle always supported by Python) to interactive control of WX, Qt -and GTK apps. Under OSX, however, this requires that ipython is -installed by calling the special pythonw script at installation time, -which takes care of coordinating things with Apple's graphical environment. - -So when installing under OSX, it is best to use the following command:: - - $ sudo pythonw setup.py install --install-scripts=/usr/local/bin - -or - - $ sudo pythonw setup.py install --install-scripts=/usr/bin - -depending on where you like to keep hand-installed executables. - -The resulting script will have an appropriate shebang line (the first -line in the script whic begins with #!...) such that the ipython -interpreter can interact with the OS X GUI. If the installed version -does not work and has a shebang line that points to, for example, just -/usr/bin/python, then you might have a stale, cached version in your -build/scripts- directory. Delete that directory and -rerun the setup.py. - -It is also a good idea to use the special flag ``--install-scripts`` as -indicated above, to ensure that the ipython scripts end up in a location -which is part of your $PATH. Otherwise Apple's Python will put the -scripts in an internal directory not available by default at the command -line (if you use /usr/local/bin, you need to make sure this is in your -$PATH, which may not be true by default). - - -Readline problems ------------------ - -By default, the Python version shipped by Apple does not include the -readline library, so central to IPython's behavior. If you install -IPython against Apple's Python, you will not have arrow keys, tab -completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt -readline library here: -http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip - -If you are using OSX 10.4 (Tiger), after installing this package you -need to either: - - 1. move readline.so from /Library/Python/2.3 to - /Library/Python/2.3/site-packages, or - 2. install http://pythonmac.org/packages/TigerPython23Compat.pkg.zip - -Users installing against Fink's Python or a properly hand-built one -should not have this problem. - - -DarwinPorts ------------ - -I report here a message from an OSX user, who suggests an alternative -means of using IPython under this operating system with good results. -Please let me know of any updates that may be useful for this section. -His message is reproduced verbatim below: - - From: Markus Banfi - - As a MacOS X (10.4.2) user I prefer to install software using - DawinPorts instead of Fink. I had no problems installing ipython - with DarwinPorts. It's just: - - sudo port install py-ipython - - It automatically resolved all dependencies (python24, readline, - py-readline). So far I did not encounter any problems with the - DarwinPorts port of ipython. - - - -Windows instructions --------------------- - -Some of IPython's very useful features are: - - * Integrated readline support (Tab-based file, object and attribute - completion, input history across sessions, editable command line, - etc.) - * Coloring of prompts, code and tracebacks. - -.. _pyreadline: - -These, by default, are only available under Unix-like operating systems. -However, thanks to Gary Bishop's work, Windows XP/2k users can also -benefit from them. His readline library originally implemented both GNU -readline functionality and color support, so that IPython under Windows -XP/2k can be as friendly and powerful as under Unix-like environments. - -This library, now named PyReadline, has been absorbed by the IPython -team (Jörgen Stenarson, in particular), and it continues to be developed -with new features, as well as being distributed directly from the -IPython site. - -The PyReadline extension requires CTypes and the windows IPython -installer needs PyWin32, so in all you need: - - 1. PyWin32 from http://sourceforge.net/projects/pywin32. - 2. PyReadline for Windows from - http://ipython.scipy.org/moin/PyReadline/Intro. That page contains - further details on using and configuring the system to your liking. - 3. Finally, only if you are using Python 2.3 or 2.4, you need CTypes - from http://starship.python.net/crew/theller/ctypes(you must use - version 0.9.1 or newer). This package is included in Python 2.5, - so you don't need to manually get it if your Python version is 2.5 - or newer. - -Warning about a broken readline-like library: several users have -reported problems stemming from using the pseudo-readline library at -http://newcenturycomputers.net/projects/readline.html. This is a broken -library which, while called readline, only implements an incomplete -subset of the readline API. Since it is still called readline, it fools -IPython's detection mechanisms and causes unpredictable crashes later. -If you wish to use IPython under Windows, you must NOT use this library, -which for all purposes is (at least as of version 1.6) terminally broken. - - -Installation procedure ----------------------- - -Once you have the above installed, from the IPython download directory -grab the ipython-XXX.win32.exe file, where XXX represents the version -number. This is a regular windows executable installer, which you can -simply double-click to install. It will add an entry for IPython to your -Start Menu, as well as registering IPython in the Windows list of -applications, so you can later uninstall it from the Control Panel. - -IPython tries to install the configuration information in a directory -named .ipython (_ipython under Windows) located in your 'home' -directory. IPython sets this directory by looking for a HOME environment -variable; if such a variable does not exist, it uses HOMEDRIVE\HOMEPATH -(these are always defined by Windows). This typically gives something -like C:\Documents and Settings\YourUserName, but your local details may -vary. In this directory you will find all the files that configure -IPython's defaults, and you can put there your profiles and extensions. -This directory is automatically added by IPython to sys.path, so -anything you place there can be found by import statements. - - -Upgrading ---------- - -For an IPython upgrade, you should first uninstall the previous version. -This will ensure that all files and directories (such as the -documentation) which carry embedded version strings in their names are -properly removed. - - -Manual installation under Win32 -------------------------------- - -In case the automatic installer does not work for some reason, you can -download the ipython-XXX.tar.gz file, which contains the full IPython -source distribution (the popular WinZip can read .tar.gz files). After -uncompressing the archive, you can install it at a command terminal just -like any other Python module, by using 'python setup.py install'. - -After the installation, run the supplied win32_manual_post_install.py -script, which creates the necessary Start Menu shortcuts for you. - - -.. upgrading: - -Upgrading from a previous version ---------------------------------- - -If you are upgrading from a previous version of IPython, you may want -to upgrade the contents of your ~/.ipython directory. Just run -%upgrade, look at the diffs and delete the suggested files manually, -if you think you can lose the old versions. %upgrade will never -overwrite or delete anything. - Initial configuration of your environment ========================================= diff --git a/docs/source/license_and_copyright.txt b/docs/source/license_and_copyright.txt index e69de29..3f4b7ad 100644 --- a/docs/source/license_and_copyright.txt +++ b/docs/source/license_and_copyright.txt @@ -0,0 +1,3 @@ +============================= +IPython Copyright and License +============================= diff --git a/docs/source/parallel/index.txt b/docs/source/parallel/index.txt index c6df8ac..63e5999 100644 --- a/docs/source/parallel/index.txt +++ b/docs/source/parallel/index.txt @@ -7,10 +7,8 @@ User Documentation .. toctree:: :maxdepth: 2 - install.txt parallel_intro.txt parallel_multiengine.txt parallel_task.txt parallel_mpi.txt - changes.txt - faq.txt +