DOC: Change code-block to ipython in r_interface.rst

[FHaase]

The documentation mainly uses the .. ipython:: directive. This changes
the code-blocks to ipython blocks so there is a unified visual style.

[datapythonista]

In this case that the tests shouldn't be executed, I find the .. code-block:: python clearer than the ipython with outputs. But replacing the doctest: +SKIP by the :verbatim: looks good.

[codecov]

Codecov Report

Merging #23906 into master will increase coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #23906      +/-   ##
==========================================
+ Coverage   92.29%   92.29%   +<.01%     
==========================================
  Files         161      161              
  Lines       51498    51500       +2     
==========================================
+ Hits        47530    47533       +3     
+ Misses       3968     3967       -1

Flag	Coverage Δ
#multiple	90.69% <ø> (ø)	⬆️
#single	42.42% <ø> (-0.01%)	⬇️

Impacted Files	Coverage Δ
pandas/io/parsers.py	95.36% <0%> (+0.06%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a7b187a...9a2d98f. Read the comment docs.

[FHaase]

I've decided to use a .. ipython:: block as it automatically changes the row numbers.

As there isn't a >>> anymore, doctests shouldn't find it as a test. This would eliminate the doctest: +SKIP which would be displayed in the documentation.

[datapythonista]

isn't the verbatim option enough for the tests to not be run?

[FHaase]

The ipython directive is an extension of IPython. see IPython sphinxext

[at]verbatim:
insert the input and output block in verbatim, but auto-increment the line numbers. Internally, the interpreter will be fed an empty string, so it is a no-op that keeps line numbering consistent. Also, can be applied to the entire .. ipython block as a directive option with :verbatim:.

[at]doctest:
Compare the pasted in output in the ipython block with the output generated at doc build time, and raise errors if they don’t match. Also, can be applied to the entire .. ipython block as a directive option with :doctest:.

Pseudo-Decorators:
Note: Only one decorator is supported per input. If more than one decorator is specified, then only the last one is used.

As the code-block directive is not part of the IPython library it wouldn't have been run anyway. This way it's just using the style of the rest of the documentation.

[FHaase]

Ohh wait, you mean something like this:

.. ipython:: python
    :verbatim:

    from rpy2.robjects import r
    r.data('iris')
    r['iris'].head()

        Sepal.Length  Sepal.Width  Petal.Length  Petal.Width Species
    0           5.1          3.5           1.4          0.2  setosa
    1           4.9          3.0           1.4          0.2  setosa

This way the output is recognized as some more input lines. That's why I utilized the In [X]: again.

[datapythonista]

In this case we can't use ipython:: python as the output can't be automatically generated. My point was that I find more readable the >>> syntax than the In [1]. And while these examples are not being run at the moment (except for the ipython::python to generate the output), it's not so important the doctest: +SKIP or the verbatim, but I think it's good to have it in case we run them later, and to make it explicit that those examples shouldn't run.

It's not very important, but personally I'd use ipython:: python for most cases, as it's the clearer, and a regular code-block for a case like this. I found those the most readable.

[FHaase]

In this case we can't use ipython:: python as the output can't be automatically generated.
verbatim stops executing the code and makes the line(s) a no-op.

verbatim: insert the input and output block in verbatim, but auto-increment the line numbers. Internally, the interpreter will be fed an empty string, so it is a no-op that keeps line numbering consistent. Also, can be applied to the entire .. ipython block as a directive option with :verbatim:.

I like >>> more as well, but this way the style would be consistent with the rest of the documentation.

[datapythonista]

I think I asked you in another issue, but didn't yet understand. What's the reason you're using ipython:: ipython with the In [1] in other parts? I guess I'm missing something, but I'd use ipython:: python everywhere, and just in this case that the output can't be generated I'd use a code-block. So, I'd never use the In [1] syntax, so in this case the >>> would be as consistent as the In [1].

[FHaase]

Ohh sorry, now I get what you mean. I was always concerned about the generated output.

.. code-block:: python
   >>> something

Would render with >>> which is different from what the rest of the documentation looks like.
However the :doctest: role only exists with the .. ipython directive, so adding all the # doctest: +SKIP
lines confused me into thinking it was intended to check by searching for >>> in the *.rst files.
Which would have been blocked by using In [X]: syntax.

[FHaase]

Well using:

.. ipython:: python
   >>> something

renders as:

In [1]: >>> something

[datapythonista]

Ok, I understand your point now. I thought you were talking about the consistency in terms of the code, not in how it is presented to the user (I thought it was always rendered the same).

lgtm then, thanks @FHaase

[jreback]

thanks @FHaase