Validate PEP-8 in docstring examples

At the moment we are automatically validating PEP-8 in our code (using flake8 . in the CI), and we also have the script scripts/validate_docstrings.py that reports errors for different formatting errors in our docstrings, and it also runs the tests to see if they work and generate the expected input. But we are not validating whether the examples follow PEP-8.

In the next example:

def head():
    """
    Return the first n rows of the Series.

    Examples
    --------
    >>> s=pd.Series([1, 2, 3, 4])
    >>> s.head(2)
    0    1
    1    2
    dtype: int64

Everything will be reported as correct, because the formatting of the docstring is the expected, and when running the examples, they work and they generated the presented output.

According to PEP-8, there should be spaces around the = in an assignment. So, we should have s = pd.Series([1, 2, 3, 4]) instead of s=pd.Series([1, 2, 3, 4]). So, the validation should report it as an error.

What we need to do is:

• Add a method in scripts/validate_docstrings.py that obtains the code in the examples (and if possible their line in the code to be presented to the user if there are errors). For what I know, the module doctest in the Python standard library provides a way to extract the code.
• Add another method that given some code, returns possible PEP-8 errors. We currently have pyflakes as a dependency, so using it is probably the best option. But if it’s better to use pycodestyle or something else, that could be an option.
• Use these methods in the validation, so errors are reported as the rest of the errors from the validation
• Add unit tests for the implemented features in scripts/tests/test_validate_docstrings.py

[FHaase]

As flake8 is already being used, wouldn’t it make sense to use flake8 plugins to check for those things?

• flake8-rst For code in docstrings and *.rst files Pull request created on conda-forge
• flake8-docstrings A plugin to flake8 to include checks provided by pep257 Already added to conda-forge

[datapythonista]

Fixed in #23399