DOC: update the pandas.Series.set_axis docstring

[astrastefania]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
###################### Docstring (pandas.Series.set_axis) ######################
################################################################################

Assign desired index to given axis.

Indexes for columns or rows can be changed by assigning
a list-like or Index.

Parameters
----------
labels : list-like, Index
    The values for the new index.

axis : int, default 0
    The value 0 indentify the rows, 1 identify the columns.

inplace : boolean, default None
    Whether to return a new NDFrame instance.

    WARNING: inplace=None currently falls back to to True, but
    in a future version, will default to False.  Use inplace=True
    explicitly rather than relying on the default.

    .. versionadded:: 0.21.0
        The signature is make consistent to the rest of the API.
        Previously, the "axis" and "labels" arguments were respectively
        the first and second positional arguments.

Returns
-------
renamed : NDFrame or None
    An object of same type as caller if inplace=False, None otherwise.

See Also
--------
pandas.DataFrame.rename_axis : Alter the name of the index or columns.

Examples
--------
>>> s = pd.Series([1, 2, 3])
>>> s
0    1
1    2
2    3
dtype: int64
>>> s.set_axis(['a', 'b', 'c'], axis=0, inplace=False)
a    1
b    2
c    3
dtype: int64
>>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
>>> df.set_axis(['a', 'b', 'c'], axis=0, inplace=False)
   A  B
a  1  4
b  2  5
c  3  6
>>> df.set_axis(['I', 'II'], axis=1, inplace=False)
   I  II
0  1   4
1  2   5
2  3   6
>>> df.set_axis(['i', 'ii'], axis=1, inplace=True)
>>> df
   i  ii
0  1   4
1  2   5
2  3   6

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Private classes (['NDFrame']) should not be mentioned in public docstring.

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

[pep8speaks]

Hello @astrastefania! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 13, 2018 at 21:12 Hours UTC

[TomAugspurger]

    axis : {0 or 'index', 1 or 'columns'}, default 0

[TomAugspurger]

And modify the description to say that the string forms are also acepted.

[astrastefania]

Thanks, so axis : {0 or 'index', 1 or 'columns'}, default 0 is enough or should I mention int, str too?

[astrastefania]

OK, I added the fixes mentioned :)

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@d7bcb22). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master   #20164   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49152           
  Branches          ?        0           
=========================================
  Hits              ?    45074           
  Misses            ?     4078           
  Partials          ?        0

Flag	Coverage Δ
#multiple	90.08% <100%> (?)
#single	41.84% <100%> (?)

Impacted Files	Coverage Δ
pandas/core/generic.py	95.84% <100%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d7bcb22...bf8b7c6. Read the comment docs.

[TomAugspurger]

Pushed an update.

We weren't actually using the set_axis in a shared doc (I think). I converted it to a regular docstring. Going to let the tests finish before merging, in case I missed something. Running locally as well.

@astrastefania let me know if you see that the test finish before I do.

[astrastefania]

Hey @TomAugspurger, should I update anything in here?
I'm happy to understand better how CircleCI works. :)

[TomAugspurger]

I think those failures are unrelated. Will look more closely tomorrow.

…

________________________________ From: Stefania Delprete <notifications@github.com> Sent: Thursday, March 15, 2018 5:06:38 PM To: pandas-dev/pandas Cc: Tom Augspurger; Mention Subject: Re: [pandas-dev/pandas] DOC: update the pandas.Series.set_axis docstring (#20164) Hey @TomAugspurger<https://github.com/tomaugspurger>, should I update anything in here? I'm happy to understand better how CircleCI works. :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#20164 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ABQHIt0PrfFNqDnh_2x4OueWdmjSln0Cks5teuXugaJpZM4SlTV0>.

[TomAugspurger]

@astrastefania those failures were fixed by #20288. It failed on CircleCI since it tests your exact branch, which doesn't include those changes. It passed on TravisCI since it tests a merge commit, master + your changes, which does include those change (since they're on master).

We could merge master to this branch and repush and things should pass. But I'm just going to merge. Thanks!