##// 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 4 Overview of the IPython configuration system
5 5 ============================================
6 6
7 This section describes the IPython configuration system. Starting with version
8 0.11, IPython has a completely new configuration system that is quite
9 different from the older :file:`ipythonrc` or :file:`ipy_user_conf.py`
10 approaches. The new configuration system was designed from scratch to address
11 the particular configuration needs of IPython. While there are many
12 other excellent configuration systems out there, we found that none of them
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>`
7 This section describes the IPython configuration system.
8
9 The following discussion is for users who want to configure
10 IPython to their liking. Developers who want to know how they can
11 enable their objects to take advantage of the configuration system
12 should consult the :ref:`developer guide <developer_guide>`
28 13
29 14 The main concepts
30 15 =================
@@ -317,7 +302,7 b' overridden by the ``config_file`` command line flag.'
317 302
318 303 To generate the default configuration files, do::
319 304
320 $> ipython profile create
305 $ ipython profile create
321 306
322 307 and you will have a default :file:`ipython_config.py` in your IPython directory
323 308 under :file:`profile_default`. If you want the default config files for the
@@ -333,10 +318,10 b' profile with:'
333 318
334 319 .. sourcecode:: bash
335 320
336 $> ipython locate
321 $ ipython locate
337 322 /home/you/.ipython
338 323
339 $> ipython locate profile foo
324 $ ipython locate profile foo
340 325 /home/you/.ipython/profile_foo
341 326
342 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 357 .. code-block:: bash
373 358
374 ipython profile create <name>
359 $ ipython profile create <name>
375 360
376 361 which adds a directory called ``profile_<name>`` to your IPython directory. Then
377 362 you can load this profile by adding ``--profile=<name>`` to your command line
@@ -399,18 +384,14 b' name.'
399 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
403 particular profile, the easiest way is to add Python (.py) or IPython (.ipy) scripts
404 to your :file:`<profile>/startup` directory. Files in this directory will always be
405 executed as soon as the IPython shell is constructed, and before any other code or
406 scripts you have specified. If you have multiple files in the startup directory,
407 they will be run in lexicographical order, so you can control the ordering by adding
408 a '00-' prefix.
409
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.
387 If you want some code to be run at the beginning of every IPython session with
388 a particular profile, the easiest way is to add Python (``.py``) or
389 IPython (``.ipy``) scripts to your :file:`<profile>/startup` directory. Files
390 in this directory will always be executed as soon as the IPython shell is
391 constructed, and before any other code or scripts you have specified. If you
392 have multiple files in the startup directory, they will be run in
393 lexicographical order, so you can control the ordering by adding a '00-'
394 prefix.
414 395
415 396
416 397 .. _commandline:
@@ -429,7 +410,7 b' object. Values are assigned in much the same way as in a config file:'
429 410
430 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 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 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 439 Aliases
459 440 *******
@@ -463,11 +444,11 b' to specify the whole class name:'
463 444
464 445 .. code-block:: bash
465 446
466 $> ipython --profile myprofile
447 $ ipython --profile myprofile
467 448 # and
468 $> ipython --profile='myprofile'
449 $ ipython --profile='myprofile'
469 450 # are equivalent to
470 $> ipython --BaseIPythonApplication.profile='myprofile'
451 $ ipython --BaseIPythonApplication.profile='myprofile'
471 452
472 453 Flags
473 454 *****
@@ -480,17 +461,17 b' For instance:'
480 461
481 462 .. code-block:: bash
482 463
483 $> ipcontroller --debug
464 $ ipcontroller --debug
484 465 # is equivalent to
485 $> ipcontroller --Application.log_level=DEBUG
466 $ ipcontroller --Application.log_level=DEBUG
486 467 # and
487 $> ipython --matploitlib
468 $ ipython --matploitlib
488 469 # is equivalent to
489 $> ipython --matplotlib auto
470 $ ipython --matplotlib auto
490 471 # or
491 $> ipython --no-banner
472 $ ipython --no-banner
492 473 # is equivalent to
493 $> ipython --TerminalIPythonApp.display_banner=False
474 $ ipython --TerminalIPythonApp.display_banner=False
494 475
495 476 Subcommands
496 477 -----------
@@ -502,14 +483,14 b' Some IPython applications have **subcommands**. Subcommands are modeled after'
502 483
503 484 .. code-block:: bash
504 485
505 $> ipython qtconsole --profile myprofile
486 $ ipython qtconsole --profile myprofile
506 487
507 488 and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
508 489 stop, engines).
509 490
510 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 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