DOC: Fix the docstring of xs in pandas/core/generic.py

[datapythonista]

pandas docstring are expected to follow the format defined in https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html

This includes among other things:

• There is a short description fitting in one line (there can be a longer one after that).
• The description of the parameters, the returns section, and the see also items, starts with a capital letter and ends with a period.
• In the Return section there is no name before the type (e.g. transformed : Series) but just the type (e.g. Series) in the first line.
• The examples are valid PEP-8 code, and when executed, they produce the shown input.

We should make the required adjustments in the docstring of the function xs in pandas/core/generic.py.

We should validate the docstring with our validator (which does not validate all the formats, but some):

• ./scripts/validate_docstrings.py pandas.Series.xs

And we should validate the PEP-8 of the examples (note that the next command will validate the PEP-8 of all examples, just make sure that none of the shown is in the function being addressed, the rest will be fixed in separate issues):

• flake8 --doctests pandas/core/generic.py

[hweersot]

I want to start contributing with this issue
If you don't mind I'd like to get this one.
And would you give me some advices with process?

[datapythonista]

Sure, go for it.

You can follow these instructions: https://python-sprints.github.io/pandas/dashboard.html

Couple of things are specific to sprints, but almost everything applies. Also remember the flake8 --doctests pandas/core/generic.py validation in the issue description, which is not in the checklist.

[hweersot]

I have some question.

    >>> df
                        A  B  C  D
    first second third
    bar   one    1      4  1  8  9
          two    1      7  5  5  0
    baz   one    1      6  6  8  0
          three  2      5  3  5  3

I have deal with other examples, but I have no idea with how to declare dataframe in this case.

df.xs(('baz', 'three'))
A B C D
third
2 5 3 5 3
>>> df.xs('one', level=1)
A B C D
first third
bar 1 4 1 8 9
baz 1 6 6 8 0
>>> df.xs(('baz', 2), level=[0, 'third'])
A B C D
second
three 5 3 5 3

And this is the result of cross-section.

Which statement is expected when I validate pandas.Series.xs with validate_docstrings.py??
I have no statements but just opening source latter file

[datapythonista]

pandas.MultiIndex has some methods like from_product or from_tuples that can be used. Or an easier way may be to create regular columns and then set them as the index .set_index(['level1', 'level2']). I'd use that in the examples, to not make them too complicated.

[hweersot]

Ok. Sorry for taking too long time.
I'll do it ASAP

[hweersot]

I'm sorry to say that I gave up this issue.
Not because of modifing docs, but I have no idea with error ocurred in my OS during validation.
I tried a lot, but maybe someone else could make a PR much better,
Sorry for waiting so long time.

[srihari-palivela]

I'd like to work on this issue

[tlentali]

Hi ! I will help on this one