DOC: Ex03 errors docstrings
State: closed

pandas.io.formats.style.Styler.map

<img width="382" alt="image" src="https://github.com/pandas-dev/pandas/assets/77875500/d56abac1-7369-45e3-baa1-c59f4a82400e">

pandas.io.formats.style.Styler.apply_index

<img width="446" alt="image" src="https://github.com/pandas-dev/pandas/assets/77875500/41be81a0-2cf3-4a9d-bfc9-dd4c5a73e75d">

pandas.io.formats.style.Styler.map_index

<img width="418" alt="image" src="https://github.com/pandas-dev/pandas/assets/77875500/778d62b1-79e9-4993-a690-5a2871d6c57d">

pandas.io.formats.style.Styler.format

<img width="397" alt="image" src="https://github.com/pandas-dev/pandas/assets/77875500/76a3fdf3-ed58-452f-ba71-3324e73836cb">


Labels:
name: Docs

Comments:
Uh, @datapythonista  I believe the CI failure is connected to the variable we discussed earlier.

It seems related to `map_index` and `apply_index`, because the doc is dynamic.

When `scripts/validate_docstrings.py --format=actions --errors=EX03 pandas.io.formats.style.Styler.map_index;`

<img width="468" alt="image" src="https://github.com/pandas-dev/pandas/assets/77875500/c20068e7-c6e0-4fd6-a288-2fb6c8a9da44">

And if we back to `s`, it seems reasonable. And indeed the `ret` and `ret2` related to different variable.

<img width="539" alt="image" src="https://github.com/pandas-dev/pandas/assets/77875500/b2f37ef1-d1e0-4cf2-af17-4f11dfd179f0">


Part of the output of  `scripts/validate_docstrings.py --format=actions --errors=EX03 pandas.io.formats.style.Styler.map_index`
<img width="475" alt="image" src="https://github.com/pandas-dev/pandas/assets/77875500/a00b973a-bea2-4d9f-9a73-023486c03645">

I'm attempting to address it in a more sensible manner. When considering changing 's' in 'ret', which option do you think is preferable, @datapythonista?
I think one of the tricky parts of that docstring is that it's a template reused in more than one place, so we'll have to make sure that all the resulting docstrings look good.

I guess the problem may be that linting is not happy with variables with only one character. Ideally we want to understand the example, and use a variable name that is meaningful instead. If you can't find a good name, maybe something like `value` can be good enough. In this case it does seem like the input of the function is the label of the index. Maybe `label` is an option too.
> I guess the problem may be that linting is not happy with variables with only one character. 

The previous error doesn't appear to be solely due to using a one-character variable name. Instead, I believe it stems from the fact that in

https://github.com/pandas-dev/pandas/blob/e3796929283c91f0f96fed3d37b2e85bf4007ef9/pandas/io/formats/style.py#L1936-L1937C29

`s` is not set as `{var}` for reuse. Consequently, when `{ret}` is replaced with another value where `s` is not present in `{ret}`, it triggers an error

My latest solution involves setting `s` to `{var}`, aligning with our initial expectations. The oversight was simply due to a minor lapse in proper configuration. I'm glad to report that the CI is now passing successfully.

>  In this case it does seem like the input of the function is the label of the index. Maybe label is an option too

If I am not mistaken, I plan to enhance the readability and precision of the variable names in the example.
Thanks @luke396, I had a look at https://pandas.pydata.org/preview/56905/docs/reference/api/pandas.io.formats.style.Styler.apply_index.html#pandas.io.formats.style.Styler.apply_index and everything seem perfect with the variable name now.

Thanks a lot for the work on this.