DOC: flake8 flagging template strings in docstrings as syntax errors

[kkangs0226]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.io.formats.style.Styler.apply_index.html
https://pandas.pydata.org/docs/reference/api/pandas.io.formats.style.Styler.background_gradient.html

Documentation problem

Template strings that are in the first line of the doctest i.e. line starting with >>>, are flagged as syntax errors.

A guess is that perhaps flake8 identifies the doctests chunks & runs the syntax checking before the docstrings are rendered, and there is perhaps a bug (or perhaps there are other reasons) where the string interpolation is flagged as a syntax error for the first line.

Detailed testing & more information about this error can be found here #51356 (comment)

Suggested fix for documentation

Would need to discuss how to fix the template problem in doctests.

[jayam30]

Hey I want to start my contribution with this, could I be assigned this

[MarcoGorelli]

@jayam30 please stop leaving the same comment on all issues - please consider this a warning

[wcgonzal]

Take if nobody is currently working on this.

[MarcoGorelli]

thanks for reporting

to be honest I don't think there's much we can do here, the templates are used when creating the docstrings - flake8 errors should be fixed using validate_docstrings with the EX03 code, not by running flake8. Running flake8 directly has been useful for fixing issues (thanks @kkangs0226 !), but it's not what we run in CI, so I don't think there's much that needs fixing here

closing then, but thanks for your report and contributions!