DOC: RT03 fix for min,max,mean,meadian,kurt,skew
State: closed

This PR will fix RT03 error for min,max,mean,meadian,kurt,skew methods

- [x] xref #57416 
- [ ] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [ ] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [ ] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) to new arguments/methods/functions.
- [ ] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.


Labels:
name: Docs

Comments:
/preview
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/57682/
Thanks @YashpalAhlawat, great job.

There are couple of details that would be good to address. This docstring is also being reused by `Series` methods, you can see how it looks here:

https://pandas.pydata.org/preview/pandas-dev/pandas/57682/docs/reference/api/pandas.Series.kurt.html

Few things:
- Can  we also remove the `Series.kurt`... methods from the validation as we did with the `DataFrame` methods?
- If you see in the description you added, it says `applying the kurt function to the DataFrame elements` when we are in the `Series` docstring. Can you use a parameter so it says `... Series elements` please?
- Finally, this is not from your PR, but if you see the docstring in the link, it says `scalar or scalar` for the return type, which doesn't make sense. I think for DataFrame it should says `Series or scalar` and for Series it should say simply `scalar`. Can you have a look to see if this is really the case, and make the docstring show the correct types please?

Thanks for the help with this!
> Thanks @YashpalAhlawat, great job.
> 
> There are couple of details that would be good to address. This docstring is also being reused by `Series` methods, you can see how it looks here:
> 
> https://pandas.pydata.org/preview/pandas-dev/pandas/57682/docs/reference/api/pandas.Series.kurt.html
> 
> Few things:
> 
> * Can  we also remove the `Series.kurt`... methods from the validation as we did with the `DataFrame` methods?
> * If you see in the description you added, it says `applying the kurt function to the DataFrame elements` when we are in the `Series` docstring. Can you use a parameter so it says `... Series elements` please?
> * Finally, this is not from your PR, but if you see the docstring in the link, it says `scalar or scalar` for the return type, which doesn't make sense. I think for DataFrame it should says `Series or scalar` and for Series it should say simply `scalar`. Can you have a look to see if this is really the case, and make the docstring show the correct types please?
> 
> Thanks for the help with this!

@datapythonista , All points has been addressed. If you have any other approach in mind to address third point. I will be happy to make changes in my implementation for that.

Thanks

Thanks for the updates @YashpalAhlawat. It would be good to change the parameters of `name1`, `name2` as needed in a static way. The idea is that we have a template we use in different methods. And when reusing the template we specify the values for each function. So, you can have a value `Series or scalar` or `scalar` as appropriate so the type renders correctly without requiring extra complexity. Does this make sense?
> Thanks for the updates @YashpalAhlawat. It would be good to change the parameters of `name1`, `name2` as needed in a static way. The idea is that we have a template we use in different methods. And when reusing the template we specify the values for each function. So, you can have a value `Series or scalar` or `scalar` as appropriate so the type renders correctly without requiring extra complexity. Does this make sense?

@datapythonista , I have implemented a solution in a similar manner. It is functioning as expected. I would appreciate your feedback. If you believe there is a better approach, I am open to making the necessary changes.
/preview

Thanks a lot for working on this @YashpalAhlawat.

I've been checking, and it's quite complex how we are generating these docstrings. I think I'm happy to merge your changes as they are if you want, but while it fixes the problems with the docstrings you are fixing here, it adds even a bit more complexity to the function. Also, there will still be docstrings with related problems, for example https://pandas.pydata.org/docs/reference/api/pandas.Series.sum.html will still have the `scalar or scalar` return.

What do you think about replacing `name1` and `name2` and using `return_type` instead containing both values together for all cases (e.g. `DataFrame or Series`, `Series or scalar`, `scalar`)? In some cases, that would require changing the description of the return, to avoid having the type (same as you did in one of the iterations of this PR, focusing on what is being returned conceptually instead of in the types).

Finally, I think it'd be good to move the code of condition `if ndim == 1:` at the end of the `make_doc` function, so you can have the `if` you added together with the settings of the other `return_type` (`name1` and `name2` now).

So, you'll have something like:

```python
      if ndim == 1:
          return_type = "Series or scalar"
          axis_descr = "{index (0)}"
      else:
          if base_doc in (_num_doc, _sum_prod_doc):
              return_type = "scalar"
          else:
              return_type = "Series or scalar"
          axis_descr = "{index (0), columns (1)}"
```

Not sure if what we should do is to remove this function and simplify how docstrings are being reused, but I think this way at least things don't get too much more complicated than now. What do you think?
@datapythonista ,

I would love to change the code for all. 
But #57683 focuses on removing such code and adding string directly to methods.

Shouldn't I remove all logic and put doc strings directly to methods.

> Shouldn't I remove all logic and put doc strings directly to methods.

Yes, if you want to do that, I think for this case everybody will surely agree, the complexity here is quite high as you already experienced. If you do it, it's better to do it step by step, we can probably have a PR for every base docstring. Or as you think it makes sense, but not replacing the whole `make_doc` function in a single PR, that'll be very hard to review.

Thanks a lot for the work on this @YashpalAhlawat 
@datapythonista ,

I have updated the code as per suggestion.

For removing all the code and putting plain docstrings in methods. That can be picked separately once this PR is merged.
/preview
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/57682/
/preview
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/57682/
@YashpalAhlawat you'll have to resolve the conflicts, we changed how the ignored errors are specified in `code_checks.sh`.
@datapythonista , Could you please review this. So that I can close this and move on to some other task.

Thanks!!
Thanks for the PR but it appears this PR has gone stale and needs a rebase. Closing but feel free to ping once you have addressed the conflicts and want to keep working on this