From d7ff065a43a0167586c8368714822afece647cea 2017-03-09 18:38:06 From: Matthias Bussonnier Date: 2017-03-09 18:38:06 Subject: [PATCH] [Doc] Rework tutorial --- diff --git a/docs/source/interactive/index.rst b/docs/source/interactive/index.rst index 89a98a7..160a190 100644 --- a/docs/source/interactive/index.rst +++ b/docs/source/interactive/index.rst @@ -1,11 +1,11 @@ -================================== -Using IPython for interactive work -================================== +======== +Tutorial +======== This section of IPython documentation will walk you through most of the IPython functionality. You do not need to have any deep knowledge of Python to read this tutorial, though some sections might make slightly more sense if you have already -done some work in the REPL. +done some work in the classic Python REPL. .. note:: diff --git a/docs/source/interactive/tutorial.rst b/docs/source/interactive/tutorial.rst index b6fd550..a2a7ea2 100644 --- a/docs/source/interactive/tutorial.rst +++ b/docs/source/interactive/tutorial.rst @@ -10,12 +10,56 @@ more than the standard prompt. Some key features are described here. For more information, check the :ref:`tips page `, or look at examples in the `IPython cookbook `_. +If you haven't done that yet see `how to install ipython `_ . + If you've never used Python before, you might want to look at `the official tutorial `_ or an alternative, `Dive into Python `_. -The four most helpful commands -=============================== +Start IPython by issuing the ``ipython`` command from your shell, you should be +greeted by the following:: + + Python 3.6.0 + Type 'copyright', 'credits' or 'license' for more information + IPython 6.0.0.dev -- An enhanced Interactive Python. Type '?' for help. + + In [1]: + + +Unlike the Python REPL, you will see that the input prompt is ``In [N]:`` +instead of ``>>>``. The number ``N`` in the prompt will be used later in this +tutorial but should usually not impact the computation. + +You should be able to type single line expressions and press enter to evaluate +them. If an expression is incomplete, IPython will automatically detect this and +add a new line when you press ``Enter`` instead of evaluating. + +Feel free to explore multi-line text edition. Unlike many other REPL with +IPython you can use the up and down arrow keys when editing multi-line +code blocks. + +Here is an example of a longer interaction with the IPython REPL we often refer +to as an IPython _session_ :: + + In [1]: print('Hello IPython') + Hello IPython + + In [2]: 21 * 2 + Out[2]: 42 + + In [3]: def say_hello(name): + ...: print('Hello {name}'.format(name=name)) + ...: + +We won't get into details right now, but unlike the standard python REPL you +will notice a few difference. First your code should be syntax-highlighted as +you type. + +Second, you will see that some results will have an ``Out[N]:`` prompt, while +some other do not. We'll come to this later. + +The four most helpful commands +============================== The four most helpful commands, as well as their brief description, is shown to you in a banner, every time you start IPython: @@ -70,8 +114,8 @@ in line and cell mode:: 100000 loops, best of 3: 7.76 us per loop In [2]: %%timeit x = range(10000) - ...: max(x) - ...: + ...: max(x) + ...: 1000 loops, best of 3: 223 us per loop The builtin magics include: