Feature: Per-code-block options

[timhoffm]

I would like to pass through options to .. code-block::.

Syntax proposal: Support a comment at the start of code blocks

# sphinx_gallery_code_block_options
#     :caption: Example
#     :emphasize-lines: 6

import matplotlib.pyplot as plt
import numpy as np

x = np.arange(10)
y = np.exp(x)
plt.plot(x, y)

such that the resulting ReST is

.. code-block::
    :caption: Example
    :emphasize-lines: 6

    import matplotlib.pyplot as plt
    import numpy as np

    x = np.arange(10)
    y = np.exp(x)
    plt.plot(x, y)

[lucyleeow]

That syntax won't work with our extract_file_config, what about making it a dict and sphinx gallery deals with the syntax? It also prevent any indenting errors from the user.

[timhoffm]

Thanks for the feedback. I'm not wedded to a particular syntax. Do I understand correctly that configurations have to be single-line? Could you give an example how the dict would look like?

[lucyleeow]

Do I understand correctly that configurations have to be single-line?

Hmm maybe, I'll have a look at the regex. - yeah i think it is single line

I was thinking maybe:

sphinx_gallery_code_block_options = {'caption': 'Example', 'emphasize-lines': 6}

WDYT?

[timhoffm]

My original intention was to mimic the ReST declaration as close as possible. But since multiple lines is not supported, a dict seems like a reasonably simple alternative in terms of clarity of expression and parsing effort.

Note that there are value-less options and we have to define how these should be described, e.g. {'linenos': ''}.

Also, all parameters need to be strings or trivially be convertable to strings:

{'emphasize-lines: '3'}  # ok
{'emphasize-lines: '3, 5'}  # ok
{'emphasize-lines': 3}  # ok - if we want to be tolerant
{'emphasize-lines': 3, 5}  # not possible

[lucyleeow]

Also, all parameters need to be strings or trivially be convertable to strings:

Good point. I am happy to force strings?

I am not opposed to multi-line/ReSt declaration implementation. It's just that all other per-file or per-code block config seem to use the extract_file_config, so it would be nice if this could as well from a maintenance point of view. If we can add it simply without adding too much burden, that would be acceptable too.

[timhoffm]

Ok, should I start to look into the implementation (one way or the other)?

[lucyleeow]

Yes please go ahead!