[IPython-dev] ipython sphinx directive

[Hans Meine]

Hi John,

nice plan that you're following, I am looking forward to the result of this.

On Saturday 07 November 2009 16:21:27 John Hunter wrote:
> In the alternative syntax, call it "ipython prompt", The rst document
> includes input and output prompts, but the embedded ipython
> interpreter detects the input prompt string 'In [\\d]:' and executes
> the code.  I'm leaning towards this syntax, [...]

+1

> * one of the strengths of rest is that is is human readable in the
>   plain text form. [...]

Exactly.

> * how do we handle numbering?  I'm pretty sure we want auto-numbering.

+1

>   With real-world experience writing a chapter using ipython session
>   dumps heavily, I find that you frequently want to change a thing or
>   two, and the prompt numbering gets out of whack.

Exactly.

>   Or you come back
>   later with a fresh ipython session and insert something into the
>   middle of the chapter and your ipython prompt numbers are
>   non-monotonic.  So I propose auto-numbering, even for ``@verbatim``
>   inputs, where the embedded interpreter will use your input and
>   output, but will use its internal prompt counter.

Yes, please.

>   I am punting on
>   use of things like ``_10`` to refer to the 10th output -- too hard.
>   However, we often want to refer to the input and output line number
>   in our narrative text, like "the ``std`` on input line ``In [8]``
>   does such-and-such" which we cannot easily do with auto-numbering.
>   One solution is to support a new role, something like::
>
>
>     .. ipython::
>
>        In [7]: x.mean()
>        Out[7]: 4.5
>
>        .. _std_x:
>        In [8]: x.std()
>        Out[8]: 2.8722813232690143
>
>
>   which we can refer to in our text like::
>
>      the ``std`` call on input line ``In [:iref:`std_x`]`` does such and
> such.
>
>   a little perl-esque and ugly, but may get the job done.

+1

BTW: I recently found this nice HTML/CSS/JS trick:
  http://diveintopython3.org/packaging.html
Look at the examples, e.g. under 16.2, where there are circled numbers 
referenced below.  When you move the mouse over them, they get highlighted 
together.

> * What should be rendered for output: the session output or the
>   ipython interpreter output.  [...]
>   I think the only workable solution is to use *ipython's* output and
>   not the user output.

Sounds reasonable to me, as do the proposed pseudo-decorators.

Have a nice day,
  Hans