[IPython-dev] ipython sphinx directive
Wed Nov 18 07:01:17 CST 2009
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, [...]
> * one of the strengths of rest is that is is human readable in the
> plain text form. [...]
> * how do we handle numbering? I'm pretty sure we want auto-numbering.
> 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.
> 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.
> 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 ``
> does such-and-such" which we cannot easily do with auto-numbering.
> One solution is to support a new role, something like::
> .. ipython::
> In : x.mean()
> Out: 4.5
> .. _std_x:
> In : x.std()
> Out: 2.8722813232690143
> which we can refer to in our text like::
> the ``std`` call on input line ``In [:iref:`std_x`]`` does such and
> a little perl-esque and ugly, but may get the job done.
BTW: I recently found this nice HTML/CSS/JS trick:
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
> * 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,
More information about the IPython-dev