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

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


Labels:
name: Docs
name: Code Style
description: Code style, linting, code_checks

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23906?src=pr&el=h1) Report
> Merging [#23906](https://codecov.io/gh/pandas-dev/pandas/pull/23906?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/a7b187ab42c48342478ed8664145f21578f50622?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/23906/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/23906?src=pr&el=tree)

```diff
@@            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% <ø> (ø)` | :arrow_up: |
| #single | `42.42% <ø> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/23906?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/parsers.py](https://codecov.io/gh/pandas-dev/pandas/pull/23906/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhcnNlcnMucHk=) | `95.36% <0%> (+0.06%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23906?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23906?src=pr&el=footer). Last update [a7b187a...9a2d98f](https://codecov.io/gh/pandas-dev/pandas/pull/23906?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

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.
isn't the verbatim option enough for the tests to not be run?
The `ipython` directive is an extension of `IPython`. see [IPython sphinxext](https://ipython.readthedocs.io/en/stable/sphinxext.html)

> `[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.
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.
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.
> 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.
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]`.
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.
Well using:
```
.. ipython:: python
   >>> something
```

renders as:
```
In [1]: >>> something
```
thanks @FHaase