##// END OF EJS Templates
Merge pull request #3905 from dpsanders/config_overview_update...
Min RK -
r12082:c52cec81 merge
parent child Browse files
Show More
@@ -4,27 +4,12 b''
4 Overview of the IPython configuration system
4 Overview of the IPython configuration system
5 ============================================
5 ============================================
6
6
7 This section describes the IPython configuration system. Starting with version
7 This section describes the IPython configuration system.
8 0.11, IPython has a completely new configuration system that is quite
8
9 different from the older :file:`ipythonrc` or :file:`ipy_user_conf.py`
9 The following discussion is for users who want to configure
10 approaches. The new configuration system was designed from scratch to address
10 IPython to their liking. Developers who want to know how they can
11 the particular configuration needs of IPython. While there are many
11 enable their objects to take advantage of the configuration system
12 other excellent configuration systems out there, we found that none of them
12 should consult the :ref:`developer guide <developer_guide>`
13 met our requirements.
14
15 .. warning::
16
17 If you are upgrading to version 0.11 of IPython, you will need to migrate
18 your old :file:`ipythonrc` or :file:`ipy_user_conf.py` configuration files
19 to the new system. You may want to read the section on
20 :ref:`configuring IPython <configuring_ipython>`. There are also some ideas
21 `on the IPython wiki <http://wiki.ipython.org/Cookbook/Moving_config_to_IPython_0.11>`_
22 about this.
23
24 The discussion that follows is focused on teaching users how to configure
25 IPython to their liking. Developers who want to know more about how they
26 can enable their objects to take advantage of the configuration system
27 should consult our :ref:`developer guide <developer_guide>`
28
13
29 The main concepts
14 The main concepts
30 =================
15 =================
@@ -317,7 +302,7 b' overridden by the ``config_file`` command line flag.'
317
302
318 To generate the default configuration files, do::
303 To generate the default configuration files, do::
319
304
320 $> ipython profile create
305 $ ipython profile create
321
306
322 and you will have a default :file:`ipython_config.py` in your IPython directory
307 and you will have a default :file:`ipython_config.py` in your IPython directory
323 under :file:`profile_default`. If you want the default config files for the
308 under :file:`profile_default`. If you want the default config files for the
@@ -333,10 +318,10 b' profile with:'
333
318
334 .. sourcecode:: bash
319 .. sourcecode:: bash
335
320
336 $> ipython locate
321 $ ipython locate
337 /home/you/.ipython
322 /home/you/.ipython
338
323
339 $> ipython locate profile foo
324 $ ipython locate profile foo
340 /home/you/.ipython/profile_foo
325 /home/you/.ipython/profile_foo
341
326
342 These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir`
327 These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir`
@@ -371,7 +356,7 b' The general pattern is this: simply create a new profile with:'
371
356
372 .. code-block:: bash
357 .. code-block:: bash
373
358
374 ipython profile create <name>
359 $ ipython profile create <name>
375
360
376 which adds a directory called ``profile_<name>`` to your IPython directory. Then
361 which adds a directory called ``profile_<name>`` to your IPython directory. Then
377 you can load this profile by adding ``--profile=<name>`` to your command line
362 you can load this profile by adding ``--profile=<name>`` to your command line
@@ -399,18 +384,14 b' name.'
399 Startup Files
384 Startup Files
400 -------------
385 -------------
401
386
402 If you want some code to be run at the beginning of every IPython session with a
387 If you want some code to be run at the beginning of every IPython session with
403 particular profile, the easiest way is to add Python (.py) or IPython (.ipy) scripts
388 a particular profile, the easiest way is to add Python (``.py``) or
404 to your :file:`<profile>/startup` directory. Files in this directory will always be
389 IPython (``.ipy``) scripts to your :file:`<profile>/startup` directory. Files
405 executed as soon as the IPython shell is constructed, and before any other code or
390 in this directory will always be executed as soon as the IPython shell is
406 scripts you have specified. If you have multiple files in the startup directory,
391 constructed, and before any other code or scripts you have specified. If you
407 they will be run in lexicographical order, so you can control the ordering by adding
392 have multiple files in the startup directory, they will be run in
408 a '00-' prefix.
393 lexicographical order, so you can control the ordering by adding a '00-'
409
394 prefix.
410 .. note::
411
412 Automatic startup files are new in IPython 0.12. Use the
413 InteractiveShellApp.exec_files configurable for similar behavior in 0.11.
414
395
415
396
416 .. _commandline:
397 .. _commandline:
@@ -429,7 +410,7 b' object. Values are assigned in much the same way as in a config file:'
429
410
430 .. code-block:: bash
411 .. code-block:: bash
431
412
432 $> ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'
413 $ ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'
433
414
434 Is the same as adding:
415 Is the same as adding:
435
416
@@ -453,7 +434,7 b' that are single characters, in which case they can be specified with a single ``'
453
434
454 .. code-block:: bash
435 .. code-block:: bash
455
436
456 $> ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
437 $ ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
457
438
458 Aliases
439 Aliases
459 *******
440 *******
@@ -463,11 +444,11 b' to specify the whole class name:'
463
444
464 .. code-block:: bash
445 .. code-block:: bash
465
446
466 $> ipython --profile myprofile
447 $ ipython --profile myprofile
467 # and
448 # and
468 $> ipython --profile='myprofile'
449 $ ipython --profile='myprofile'
469 # are equivalent to
450 # are equivalent to
470 $> ipython --BaseIPythonApplication.profile='myprofile'
451 $ ipython --BaseIPythonApplication.profile='myprofile'
471
452
472 Flags
453 Flags
473 *****
454 *****
@@ -480,17 +461,17 b' For instance:'
480
461
481 .. code-block:: bash
462 .. code-block:: bash
482
463
483 $> ipcontroller --debug
464 $ ipcontroller --debug
484 # is equivalent to
465 # is equivalent to
485 $> ipcontroller --Application.log_level=DEBUG
466 $ ipcontroller --Application.log_level=DEBUG
486 # and
467 # and
487 $> ipython --matploitlib
468 $ ipython --matploitlib
488 # is equivalent to
469 # is equivalent to
489 $> ipython --matplotlib auto
470 $ ipython --matplotlib auto
490 # or
471 # or
491 $> ipython --no-banner
472 $ ipython --no-banner
492 # is equivalent to
473 # is equivalent to
493 $> ipython --TerminalIPythonApp.display_banner=False
474 $ ipython --TerminalIPythonApp.display_banner=False
494
475
495 Subcommands
476 Subcommands
496 -----------
477 -----------
@@ -502,14 +483,14 b' Some IPython applications have **subcommands**. Subcommands are modeled after'
502
483
503 .. code-block:: bash
484 .. code-block:: bash
504
485
505 $> ipython qtconsole --profile myprofile
486 $ ipython qtconsole --profile myprofile
506
487
507 and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
488 and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
508 stop, engines).
489 stop, engines).
509
490
510 .. code-block:: bash
491 .. code-block:: bash
511
492
512 $> ipcluster start --profile=myprofile -n 4
493 $ ipcluster start --profile=myprofile -n 4
513
494
514
495
515 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``.
496 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``.
General Comments 0
You need to be logged in to leave comments. Login now