DOC: create shared includes for comparison docs, take II

[afeld]

This is a duplicate of #38771, but instead of defining :tips: in a :suppress: block, it attempts to tell flake8-rst to ignore those warnings. In other words, only one of these pull requests should be merged; the other can be closed.

• closes #xxxx
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[jreback]

great. let's see how the ci does.

[afeld]

As expected, it's getting F821 undefined name 'tips' in all those include files that reference that variable. Very possible I just don't know what I'm doing and missed some part of the configuration.

[jorisvandenbossche]

The doc build is failing because flake8-rst is not installed in that env:

Could not import extension flake8_rst.sphinxext.custom_roles (exception: No module named 'flake8_rst')

Now, for the pre-commit check, that indeed fails.
For me locally, I get the same failure. If I do :flake8-group: Ignore (which ignores the block completely), then it doesn't complain.

Short term, I would maybe just add those */includes/* files to the exclude list of flake8-rst:

pandas/setup.cfg

Lines 51 to 52 in 72ad717

	exclude =
	doc/source/development/contributing_docstring.rst

And then I would open an issue at https://github.com/kataev/flake8-rst reporting that the :flake8-add-ignore: F821 is not working for this example (it might be a bug in the package).

[afeld]

I would maybe just add those /includes/ files to the exclude list of flake8-rst

Done: #38887 (Sorry for the litany of pull requests; just wanted to make sure the different approaches can be seen independently.)

I would open an issue at https://github.com/kataev/flake8-rst reporting that the :flake8-add-ignore: F821 is not working for this example

Done: flake8-docs/flake8-rst#25

[jreback]

#38887 is before this? should this close?

[afeld]

Closing in favor of #38887.