Discussion: General ignore F821 within documentation
With PR #23381 `flake8_rst` will get merged allowing to have the `flake8` checks being run on code inside `*.rst` files within `doc/source` subfolder.

In order to make the `./ci/code_shecks.sh` script used by travis working, I had to ignore all `F821 undefined name` errors. @datapythonista and I had a brief discussion #23154 whether there should be raised an issue to fix all those errors ( @datapythonista ) or leave `F821` ignored, relying on documentation editors to design meaningful documentation without constraining `F821` issues to be fixed ( @FHaase ).

**Before I open an issue to fix all `F821` issues, I'd like to ask for a general opinion in respect of how the documentation would look like when the fixes are finished.** 

**Forcing `F821` issues to be fixed:**
* Pro:
    * Code can be copied and pasted straight from the docs.
* Contra:
    * Adds noise to the code-snippets and if overdone might lead to a more confusing documentation than without.

"Pro" Examples
---------------------
In these examples the documentation would benefit of **not** general ignoring `F821` issues:

Finding typos within code:
```
.. code-block:: python
   df = pd.DataFrame(np.random.randn(10, 4))
   dt['F'] = pd.Series([1, 2, 3, 4, 5, 6], index=pd.date_range('20130102', periods=6))
```
Adding clearness to the code:
```
.. code-block:: python
   left = pd.DataFrame({'key': ['foo', 'bar'], 'lval': [1, 2]})
   right = pd.DataFrame({'key': ['foo', 'bar'], 'rval': [4, 5]})
   pd.merge(left, right, on='key')

instead of

.. code-block:: python
   pd.merge(left_data, right_data, on='key')
```

"Contra" Examples
-------------------------
These examples would have to manually ignoring `F821` issues by adding `# noqa: F821` to the code what is beeing rendered in the documentation.

Code with semantical clear variablenames
```
By default the memory usage of the ``DataFrame``'s index is shown in the
returned ``Series``, the memory usage of the index can be suppressed by passing
the ``index=False`` argument:

.. ipython:: python
    df.memory_usage(index=False)
```
or 
```
.. code-block:: python
   with connect_to_url(url) as connection:
       pass
```

Intermediate explanations [a better example would be when s changed in block 1]
```
Using the Python ``in`` operator on a ``Series`` tests for membership in the
index, not membership among the values.

.. ipython:: python
    s = pd.Series(range(5), index=list('abcde'))
    2 in s
    'b' in s

If this behavior is surprising, keep in mind that using ``in`` on a Python
dictionary tests keys, not values, and ``Series`` are dict-like.
To test for membership in the values, use the method :meth:`~pandas.Series.isin`:

.. ipython:: python
    s.isin([2])
    s.isin([2]).any()
```

Current technical limitations
-------------------------------------
* As `flake8_rst` calls `flake8` with each of the `.. code-blocks::` or `.. ipython::` blocks individually, needing to define all variables in each block would complicate working with this directive.

* pep8 requires 2 blank lines between functions in top-level scope. `ipython` refuses to run properly with them. So [E302, E305] will become ignored as well. 

Possible compromise
----------------------------
Having a dedicated folder with code-snippets in `*.py` files which can be included via `.. includeliteral::`(?) As they represent complete examples they would be checked via `flake8` and it's possible to run tests on them ensuring up to date examples even when apis change.