Command line args in docs #564

Merged
merged 4 commits into from Jul 8, 2011
@@ -50,7 +50,7 @@ to your configuration file::
'myextension'
]
-To load that same extension at runtime, use the ``%load_ext`` magic::
+To load that same extension at runtime, use the ``%load_ext`` magic:
.. sourcecode:: ipython
@@ -336,7 +336,7 @@ Let's start by showing how a profile is used:
.. code-block:: bash
- $ ipython profile=sympy
+ $ ipython --profile=sympy
This tells the :command:`ipython` command line program to get its configuration
from the "sympy" profile. The file names for various profiles do not change. The
@@ -350,7 +350,7 @@ The general pattern is this: simply create a new profile with:
ipython profile create <name>
which adds a directory called ``profile_<name>`` to your IPython directory. Then
-you can load this profile by adding ``profile=<name>`` to your command line
+you can load this profile by adding ``--profile=<name>`` to your command line
options. Profiles are supported by all IPython applications.
IPython ships with some sample profiles in :file:`IPython/config/profile`. If
@@ -374,7 +374,7 @@ object. Values are assigned in much the same way as in a config file:
.. code-block:: bash
- $> ipython InteractiveShell.use_readline=False BaseIPythonApplication.profile='myprofile'
+ $> ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'
Is the same as adding:
@@ -394,9 +394,9 @@ used traits, so you don't have to specify the whole class name. For these **alia
.. code-block:: bash
- $> ipython profile='myprofile'
+ $> ipython --profile='myprofile'
# is equivalent to
- $> ipython BaseIPythonApplication.profile='myprofile'
+ $> ipython --BaseIPythonApplication.profile='myprofile'
Flags
-----
@@ -411,11 +411,11 @@ For instance:
$> ipcontroller --debug
# is equivalent to
- $> ipcontroller Application.log_level=DEBUG
+ $> ipcontroller --Application.log_level=DEBUG
# and
$> ipython --pylab
# is equivalent to
- $> ipython pylab=auto
+ $> ipython --pylab=auto
Subcommands
-----------
@@ -427,14 +427,14 @@ Some IPython applications have **subcommands**. Subcommands are modeled after
.. code-block:: bash
- $> ipython qtconsole profile=myprofile
+ $> ipython qtconsole --profile=myprofile
and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
stop, engines).
.. code-block:: bash
- $> ipcluster start profile=myprofile n=4
+ $> ipcluster start --profile=myprofile --n=4
To see a list of the available aliases, flags, and subcommands for an IPython application, simply pass ``-h`` or ``--help``. And to see the full list of configurable options (*very* long), pass ``--help-all``.
@@ -349,7 +349,8 @@ We basically need to be able to test the following types of code:
Nose will pick them up as long as they conform to the (flexible) conventions
used by nose to recognize tests.
-2. Python files containing doctests. Here, we have two possibilities:
+2. Python files containing doctests. Here, we have two possibilities:
+
- The prompts are the usual ``>>>`` and the input is pure Python.
- The prompts are of the form ``In [1]:`` and the input can contain extended
IPython expressions.
@@ -361,6 +362,7 @@ We basically need to be able to test the following types of code:
3. ReStructuredText files that contain code blocks. For this type of file, we
have three distinct possibilities for the code blocks:
+
- They use ``>>>`` prompts.
- They use ``In [1]:`` prompts.
- They are standalone blocks of pure Python code without any prompts.
@@ -20,16 +20,15 @@ configurable.
``%loadpy``
===========
-The ``%loadpy`` magic has been added, just for the GUI frontend. It takes any python
+The new ``%loadpy`` magic takes any python
script (must end in '.py'), and pastes its contents as your next input, so you can edit it
before executing. The script may be on your machine, but you can also specify a url, and
it will download the script from the web. This is particularly useful for playing with
examples from documentation, such as matplotlib.
.. sourcecode:: ipython
- In [6]: %loadpy
- http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py
+ In [6]: %loadpy http://matplotlib.sourceforge.net/plot_directive/mpl_examples/mplot3d/contour3d_demo.py
In [7]: from mpl_toolkits.mplot3d import axes3d
...: import matplotlib.pyplot as plt
@@ -64,12 +63,13 @@ them in your document. This is especially useful for saving_ your work.
.. _inline:
-``pylab=inline``
+``--pylab=inline``
******************
If you want to have all of your figures embedded in your session, instead of calling
-:func:`pastefig`, you can specify ``pylab=inline``, and each time you make a plot, it
-will show up in your document, as if you had called :func:`pastefig`.
+:func:`pastefig`, you can specify ``--pylab=inline`` when you start the console,
+and each time you make a plot, it will show up in your document, as if you had
+called :func:`pastefig`.
.. _saving:
@@ -116,7 +116,7 @@ if unspecified, will be guessed based on the chosen style. Similarly, there are
styles associated with each ``colors`` option.
-Screenshot of ``ipython qtconsole colors=linux``, which uses the 'monokai' theme by
+Screenshot of ``ipython qtconsole --colors=linux``, which uses the 'monokai' theme by
default:
.. image:: figs/colors_dark.png
@@ -147,7 +147,7 @@ Fonts
The QtConsole has configurable via the ConsoleWidget. To change these, set the ``font_family``
or ``font_size`` traits of the ConsoleWidget. For instance, to use 9pt Anonymous Pro::
- $> ipython qtconsole ConsoleWidget.font_family="Anonymous Pro" ConsoleWidget.font_size=9
+ $> ipython qtconsole --ConsoleWidget.font_family="Anonymous Pro" --ConsoleWidget.font_size=9
Process Management
==================
@@ -167,7 +167,7 @@ do not have to all be qt frontends - any IPython frontend can connect and run co
When you start ipython qtconsole, there will be an output line, like::
To connect another client to this kernel, use:
- --external shell=62109 iopub=62110 stdin=62111 hb=62112
+ --external --shell=62109 --iopub=62110 --stdin=62111 --hb=62112
Other frontends can connect to your kernel, and share in the execution. This is great for
collaboration. The `-e` flag is for 'external'. Starting other consoles with that flag
@@ -178,7 +178,7 @@ By default (for security reasons), the kernel only listens on localhost, so you
connect multiple frontends to the kernel from your local machine. You can specify to
listen on an external interface by specifying the ``ip`` argument::
- $> ipython qtconsole ip=192.168.1.123
+ $> ipython qtconsole --ip=192.168.1.123
If you specify the ip as 0.0.0.0, that refers to all interfaces, so any computer that can
see yours can connect to the kernel.
@@ -35,7 +35,7 @@ version 0.11, these have been removed. Please see the new ``%gui``
magic command or :ref:`this section <gui_support>` for details on the new
interface, or specify the gui at the commandline::
- $ ipython gui=qt
+ $ ipython --gui=qt
Regular Options
@@ -59,7 +59,7 @@ All options with a [no] prepended can be specified in negated form
See :ref:`Matplotlib support <matplotlib_support>`
for more details.
- ``autocall=<val>``
+ ``--autocall=<val>``
Make IPython automatically call any callable object even if you
didn't type explicit parentheses. For example, 'str 43' becomes
'str(43)' automatically. The value can be '0' to disable the feature,
@@ -83,11 +83,11 @@ All options with a [no] prepended can be specified in negated form
``--[no-]banner``
Print the initial information banner (default on).
- ``c=<command>``
+ ``--c=<command>``
execute the given command string. This is similar to the -c
option in the normal Python interpreter.
- ``cache_size=<n>``
+ ``--cache_size=<n>``
size of the output cache (maximum number of entries to hold in
memory). The default is 1000, you can change it permanently in your
config file. Setting it to 0 completely disables the caching system,
@@ -100,7 +100,7 @@ All options with a [no] prepended can be specified in negated form
Gives IPython a similar feel to the classic Python
prompt.
- ``colors=<scheme>``
+ ``--colors=<scheme>``
Color scheme for prompts and exception reporting. Currently
implemented: NoColor, Linux and LightBG.
@@ -135,7 +135,7 @@ All options with a [no] prepended can be specified in negated form
feature is off by default [which means that you have both
normal reload() and dreload()].
- ``editor=<name>``
+ ``--editor=<name>``
Which editor to use with the %edit command. By default,
IPython will honor your EDITOR environment variable (if not
set, vi is the Unix default and notepad the Windows one).
@@ -144,12 +144,12 @@ All options with a [no] prepended can be specified in negated form
small, lightweight editor here (in case your default EDITOR is
something like Emacs).
- ``ipython_dir=<name>``
+ ``--ipython_dir=<name>``
name of your IPython configuration directory IPYTHON_DIR. This
can also be specified through the environment variable
IPYTHON_DIR.
- ``logfile=<name>``
+ ``--logfile=<name>``
specify the name of your logfile.
This implies ``%logstart`` at the beginning of your session
@@ -160,7 +160,7 @@ All options with a [no] prepended can be specified in negated form
can use this to later restore a session by loading your
logfile with ``ipython --i ipython_log.py``
- ``logplay=<name>``
+ ``--logplay=<name>``
NOT AVAILABLE in 0.11
@@ -201,7 +201,7 @@ All options with a [no] prepended can be specified in negated form
of nested data structures. If you like it, you can turn it on
permanently in your config file (default off).
- ``profile=<name>``
+ ``--profile=<name>``
Select the IPython profile by name.
@@ -263,7 +263,7 @@ All options with a [no] prepended can be specified in negated form
IPython's readline and syntax coloring fine, only 'emacs' (M-x
shell and C-c !) buffers do not.
- ``TerminalInteractiveShell.screen_length=<n>``
+ ``--TerminalInteractiveShell.screen_length=<n>``
number of lines of your screen. This is used to control
printing of very long strings. Strings longer than this number
of lines will be sent through a pager instead of directly
@@ -276,16 +276,16 @@ All options with a [no] prepended can be specified in negated form
reason this isn't working well (it needs curses support), specify
it yourself. Otherwise don't change the default.
- ``TerminalInteractiveShell.separate_in=<string>``
+ ``--TerminalInteractiveShell.separate_in=<string>``
separator before input prompts.
Default: '\n'
- ``TerminalInteractiveShell.separate_out=<string>``
+ ``--TerminalInteractiveShell.separate_out=<string>``
separator before output prompts.
Default: nothing.
- ``TerminalInteractiveShell.separate_out2=<string>``
+ ``--TerminalInteractiveShell.separate_out2=<string>``
separator after output prompts.
Default: nothing.
For these three options, use the value 0 to specify no separator.
@@ -304,7 +304,7 @@ All options with a [no] prepended can be specified in negated form
``--version`` print version information and exit.
- ``xmode=<modename>``
+ ``--xmode=<modename>``
Mode for exception reporting.
@@ -103,7 +103,7 @@ calculation, we will need two top-level functions from :file:`pidigits.py`:
.. literalinclude:: ../../examples/newparallel/pidigits.py
:language: python
- :lines: 41-56
+ :lines: 47-62
We will also use the :func:`plot_two_digit_freqs` function to plot the
results. The code to run this calculation in parallel is contained in
@@ -195,7 +195,7 @@ simply start a controller and engines on a single host using the
:command:`ipcluster` command. To start a controller and 4 engines on your
localhost, just do::
- $ ipcluster start n=4
+ $ ipcluster start --n=4
More details about starting the IPython controller and engines can be found
:ref:`here <parallel_process>`
@@ -4,11 +4,6 @@
Using MPI with IPython
=======================
-.. note::
-
- Not adapted to zmq yet
- This is out of date wrt ipcluster in general as well
-
Often, a parallel algorithm will require moving data between the engines. One
way of accomplishing this is by doing a pull and then a push using the
multiengine client. However, this will be slow as all the data has to go
@@ -57,7 +52,7 @@ The easiest approach is to use the `MPIExec` Launchers in :command:`ipcluster`,
which will first start a controller and then a set of engines using
:command:`mpiexec`::
- $ ipcluster start n=4 elauncher=MPIExecEngineSetLauncher
+ $ ipcluster start --n=4 --elauncher=MPIExecEngineSetLauncher
This approach is best as interrupting :command:`ipcluster` will automatically
stop and clean up the controller and engines.
@@ -68,14 +63,14 @@ Manual starting using :command:`mpiexec`
If you want to start the IPython engines using the :command:`mpiexec`, just
do::
- $ mpiexec n=4 ipengine mpi=mpi4py
+ $ mpiexec n=4 ipengine --mpi=mpi4py
This requires that you already have a controller running and that the FURL
files for the engines are in place. We also have built in support for
PyTrilinos [PyTrilinos]_, which can be used (assuming is installed) by
starting the engines with::
- $ mpiexec n=4 ipengine mpi=pytrilinos
+ $ mpiexec n=4 ipengine --mpi=pytrilinos
Automatic starting using PBS and :command:`ipcluster`
------------------------------------------------------
@@ -110,7 +105,7 @@ distributed array. Save the following text in a file called :file:`psum.py`:
Now, start an IPython cluster::
- $ ipcluster start profile=mpi n=4
+ $ ipcluster start --profile=mpi --n=4
.. note::
@@ -19,7 +19,7 @@ To follow along with this tutorial, you will need to start the IPython
controller and four IPython engines. The simplest way of doing this is to use
the :command:`ipcluster` command::
- $ ipcluster start n=4
+ $ ipcluster start --n=4
For more detailed information about starting the controller and engines, see
our :ref:`introduction <ip1par>` to using IPython for parallel computing.
Oops, something went wrong.