Add unique output block references for literalinclude

[romanlutz]

It's sometimes useful to reference code block output in addition to produced images (using figure) or code lines (using literalinclude), so this change adds comments to the produced RST file before and after the code output as

sphx-glr-output-block-001-start
<output>
sphx-glr-output-block-001-end

which can then be referenced in other RST files as

Out:

.. literalinclude:: ../auto_examples/plot_myscript.rst
    :start-after: .. sphx-glr-output-block-001-start
    :end-before: .. sphx-glr-output-block-001-end
    :lines: 2-

The :lines: 2- part is necessary to avoid including .. code-block:. Adding Out: is also optional, but otherwise it doesn't necessarily distinguish output rendering from normal code blocks.

I'm looking for feedback on this before proceeding with potentially adding tests and other required parts for merging this PR.

closes #851

[larsoner]

This seems reasonable and useful to me. @lucyleeow can you look to see if you agree?

Eventually we'd want tests (as mentioned above) and ideally it documented and shown somewhere in the config/use docs

[lucyleeow]

Will take a look this weekend!

[lucyleeow]

Agree seems like a easy to maintain, useful addition! Tests and documentation would be good.

(The CI's are too old to look at what's erroring but running locally it seems to mostly be needing to add the extra positional argument to tests where we use execute_code_block)

[lucyleeow]

@romanlutz I'm happy to add the tests and docs for this if you would be happy with this?

[romanlutz]

@lucyleeow definitely, please go ahead! I won't get to it anytime soon I'm afraid. Thank you!

[lucyleeow]

Having a look at this I propose we adjust it slightly to use the name option of the code block directive as the 'start' indicator. E.g., to look like:

 .. code-block:: none
    :name: sphx-glr-<file_name>-output-<block_index>

    [output]

.. sphx-glr-<file_name>-output-<block_index>-end

This way we also allow people to refer to the output via :ref: and avoid the 'ugly' ':lines: 2-' part when we want to use the literalinclude. Note that I have used the source file name in the 'comment line' so that we have a unique :name: to use for :ref:.

I have tested it out and it works with the literalinclude (note the starts-with option works like so: "lines that follow the first line containing that string") e.g.,:

.. literalinclude:: ../auto_examples/plot_myscript.rst
    :start-after: sphx-glr-file-001
    :end-before: .. sphx-glr-file-001-end

It looks like this (the output was just a matplotlib lines object). There is some weird padding in the box (but this might just go away with some fiddling):

(WDYT @larsoner @romanlutz ?)

[larsoner]

That sounds like a clean solution to me!

[lucyleeow]

I've realised this would not work for html output (just 'text' output). html always has it's own header and is added at the end if captured output has both text and html, e.g.:

.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none
    :name: sphx-glr-test_gen_rst.py-output-001

    print statement


.. sphx-glr-test_gen_rst.py-output-001-end

.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div> This is the _repr_html_ div </div>
    </div>
    <br />
    <br />

We could ignore html output or add the comments around all output?

[romanlutz]

We could ignore html output or add the comments around all output?

How would we be able to add comments around all the output? If it's somehow possible (without too much extra work) that would be great, otherwise perhaps even without html is fine (?)

[lucyleeow]

I think I could manage it and I agree, it's probably best to include html even though it's slightly uglier.

Don't have the bandwidth atm but will work on this as soon as I do!