From c8faecb21d810d8fb5023bf3a399ba4aef801a40 2011-08-17 19:56:57 From: MinRK Date: 2011-08-17 19:56:57 Subject: [PATCH] update docs to reflect relaxed syntax of argparse --- diff --git a/docs/source/config/overview.txt b/docs/source/config/overview.txt index 1c75b95..3717de3 100644 --- a/docs/source/config/overview.txt +++ b/docs/source/config/overview.txt @@ -386,23 +386,39 @@ Is the same as adding: to your config file. Key/Value arguments *always* take a value, separated by '=' and no spaces. +Common Arguments +**************** + +Since the strictness and verbosity of the KVLoader above are not ideal for everyday +use, common arguments can be specified as flags_ or aliases_. + +Flags and Aliases are handled by :mod:`argparse` instead, allowing for more flexible +parsing. In general, flags and aliases are prefixed by ``--``, except for those +that are single characters, in which case they can be specified with a single ``-``, e.g.: + +.. code-block:: bash + + $> ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg + Aliases ------- -For convenience, applications have a mapping of commonly -used traits, so you don't have to specify the whole class name. For these **aliases**, the class need not be specified: +For convenience, applications have a mapping of commonly used traits, so you don't have +to specify the whole class name: .. code-block:: bash + $> ipython --profile myprofile + # and $> ipython --profile='myprofile' - # is equivalent to + # are equivalent to $> ipython --BaseIPythonApplication.profile='myprofile' Flags ----- Applications can also be passed **flags**. Flags are options that take no -arguments, and are always prefixed with ``--``. They are simply wrappers for +arguments. They are simply wrappers for setting one or more configurables with predefined values, often True/False. For instance: @@ -412,13 +428,17 @@ For instance: $> ipcontroller --debug # is equivalent to $> ipcontroller --Application.log_level=DEBUG - # and + # and $> ipython --pylab # is equivalent to $> ipython --pylab=auto + # or + $> ipython --no-banner + # is equivalent to + $> ipython --TerminalIPythonApp.display_banner=False Subcommands ------------ +*********** Some IPython applications have **subcommands**. Subcommands are modeled after diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt index 1ba2f28..550b1ab 100644 --- a/docs/source/interactive/reference.txt +++ b/docs/source/interactive/reference.txt @@ -83,7 +83,7 @@ All options with a [no] prepended can be specified in negated form ``--[no-]banner`` Print the initial information banner (default on). - ``--c=`` + ``-c `` execute the given command string. This is similar to the -c option in the normal Python interpreter. @@ -158,7 +158,7 @@ All options with a [no] prepended can be specified in negated form ipython_log.py in your current directory (which prevents logs from multiple IPython sessions from trampling each other). You can use this to later restore a session by loading your - logfile with ``ipython --i ipython_log.py`` + logfile with ``ipython -i ipython_log.py`` ``--logplay=`` diff --git a/docs/source/parallel/parallel_intro.txt b/docs/source/parallel/parallel_intro.txt index a3d3eeb..842001d 100644 --- a/docs/source/parallel/parallel_intro.txt +++ b/docs/source/parallel/parallel_intro.txt @@ -205,7 +205,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 ` diff --git a/docs/source/parallel/parallel_mpi.txt b/docs/source/parallel/parallel_mpi.txt index 3f6733c..b7d12d0 100644 --- a/docs/source/parallel/parallel_mpi.txt +++ b/docs/source/parallel/parallel_mpi.txt @@ -52,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. @@ -105,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:: diff --git a/docs/source/parallel/parallel_multiengine.txt b/docs/source/parallel/parallel_multiengine.txt index 0d288e2..f8fc5f5 100644 --- a/docs/source/parallel/parallel_multiengine.txt +++ b/docs/source/parallel/parallel_multiengine.txt @@ -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 ` to using IPython for parallel computing. diff --git a/docs/source/parallel/parallel_process.txt b/docs/source/parallel/parallel_process.txt index ffa2df1..8582f13 100644 --- a/docs/source/parallel/parallel_process.txt +++ b/docs/source/parallel/parallel_process.txt @@ -109,7 +109,7 @@ The simplest way to use ipcluster requires no configuration, and will launch a controller and a number of engines on the local machine. For instance, to start one controller and 4 engines on localhost, just do:: - $ ipcluster start --n=4 + $ ipcluster start -n 4 To see other command line options, do:: @@ -174,7 +174,7 @@ There, instruct ipcluster to use the MPIExec launchers by adding the lines: If the default MPI configuration is correct, then you can now start your cluster, with:: - $ ipcluster start --n=4 --profile=mpi + $ ipcluster start -n 4 --profile=mpi This does the following: @@ -324,7 +324,7 @@ connections on all its interfaces, by adding in :file:`ipcontroller_config`: You can now run the cluster with:: - $ ipcluster start --profile=pbs --n=128 + $ ipcluster start --profile=pbs -n 128 Additional configuration options can be found in the PBS section of :file:`ipcluster_config`. diff --git a/docs/source/parallel/parallel_task.txt b/docs/source/parallel/parallel_task.txt index aa32e34..28d34d6 100644 --- a/docs/source/parallel/parallel_task.txt +++ b/docs/source/parallel/parallel_task.txt @@ -24,7 +24,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 ` to using IPython for parallel computing. diff --git a/docs/source/parallel/parallel_winhpc.txt b/docs/source/parallel/parallel_winhpc.txt index 01e5cd1..83dedf7 100644 --- a/docs/source/parallel/parallel_winhpc.txt +++ b/docs/source/parallel/parallel_winhpc.txt @@ -257,7 +257,7 @@ Starting the cluster profile Once a cluster profile has been configured, starting an IPython cluster using the profile is simple:: - ipcluster start --profile=mycluster --n=32 + ipcluster start --profile=mycluster -n 32 The ``-n`` option tells :command:`ipcluster` how many engines to start (in this case 32). Stopping the cluster is as simple as typing Control-C.