[IPython-dev] ipython sphinx directive
Hans Meine
hans_meine at gmx.net
Wed Nov 18 08:01:17 EST 2009
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
More information about the IPython-dev
mailing list