DOC add example of Series.index #51842

ggold7046 · 2023-03-08T15:22:04Z

Added the example section.

closes #xxxx (Replace xxxx with the GitHub issue number)
Tests added and passed if fixing a bug or adding a new feature
All code checks passed.
Added type annotations 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.

Added the example section.

ggold7046 · 2023-03-09T10:50:10Z

Hi @DeaMariaLeon , could you please help me in this issue ?

The error says ---> Error: None:None:GL01:pandas.Series.index:Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between). But I saw in the series.py file ; every summary is written after leaving a blank line.

And this one too https://github.com/pandas-dev/pandas/actions/runs/4365774703/jobs/7634865667
I don't see the trailing whitespaces. I don't understand which line is too long.

MarcoGorelli

hi @ggold7046

before fixing the validation errors - did you try building this docstring locally? could you post a screenshot of how it looks please?

ggold7046 · 2023-03-09T19:24:19Z

I used gitpod for development https://pandas.pydata.org/docs/dev/development/contributing_gitpod.html and write the docstring and tested with python scripts/validate_docstrings.py pandas.Series.index . As most of the test were passed and there was no "no example section found" error, I pulled a request.

Updated the docstring.

New update.

datapythonista

Thanks @ggold7046 for the contribution, added some comments. As Marco says, you'll need to build the documentation locally. You have instructions on the contrubuting documentation.

datapythonista · 2023-03-13T18:31:28Z

pandas/core/series.py

        axis=0, doc="The index (axis labels) of the Series."
+            """


Can you make this a single text, not concatenating in this way please?

Sorry, but didn't understand. You mean like this ?
axis=0, doc="The index (axis labels) of the Series." """ A one-dimensional ndarray with hashable type axis labels. """

or this

axis=0, doc="The index (axis labels) of the Series."
""" A one-dimensional ndarray with hashable type axis labels. """

@ggold7046

Could you please use triple backticks to format code blocks? Without it, your question is really hard to read.

What @datapythonista means is that you have two strings here that will be concatenated:

a = ( "The index [...]" """ A one-dimensional [...] """ ) print(a)

The index [...] A one-dimensional [...]

Since you already have a multiline string (triple quotes), you can just merge the two:

b = """\ The index [...] A one-dimensional [...] """ print(b)

The index [...] A one-dimensional [...]

datapythonista · 2023-03-13T18:35:19Z

pandas/core/series.py

+            **Use the Series.index attribute to set the index label for 
+            the given Series object.** 
+
+            >>> s = pd.Series(['Kolkata', 'Chicago', 'Toronto', 'Lisbon'])


This example is not very realistic and confusing with the City 1, City 2 labels. Maybe something like using the city as index and then making the value a feature like population, average temperature... would make more sense.

Also, since here you're just showing the .index accessor, better create the index with Series(..., index=...) and simply show that your_series.index returns the index.

datapythonista · 2023-03-13T18:36:25Z

pandas/core/series.py

+            Pandas Series.index attribute is used to get or set the index labels 
+            of the given Series object.The object supports both 
+            integer- and label-based indexing and provides a host of methods for 
+            performing operations involving the index. 
+            The labels need not be unique but must be of the hashable type.


I think it makes more sense to link to the indexing user guide that try to explain what's indexing in a single paragraph here.

So, I have to add a see also section and mention this link ? https://pandas.pydata.org/docs/reference/api/pandas.Index.html

pmeier · 2023-03-23T11:39:33Z

Online doc preview for this PR is here: https://pandas.pydata.org/preview/51842/docs/reference/api/pandas.Series.index.html#pandas.Series.index

ggold7046 · 2023-04-01T19:13:14Z

Hi everyone,
I've updated the docstring and uploaded the rendered html docs. I couldn't posted the full doc as a single page because it was long. That is why I'm uploading in 2 pieces.

pmeier

There are currently three CI jobs failing:

They are all related to the formatting of the docstring you wrote. Let's go through them one by one inline below.

Note that all these things are very project specific. Every project defines their own style and one has to abide by that.

pandas/core/series.py

Co-authored-by: Philip Meier <[email protected]>

pmeier

You have more trailing whitespace.

pandas/core/series.py

Co-authored-by: Philip Meier <[email protected]>

pandas/core/series.py

Co-authored-by: Philip Meier <[email protected]>

ggold7046 · 2023-04-10T19:51:13Z

This is the error I'm getting while running the pre-commit install command in gitpod.

Error installing pre-commit

(pandas-dev) gitpod > /workspace/pandas $ pre-commit install An unexpected error has occurred: PermissionError: [Errno 13] Permission denied: '/home/gitpod/.cache/pre-commit' Traceback (most recent call last): File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/site-packages/pre_commit/error_handler.py", line 73, in error_handler yield File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/site-packages/pre_commit/main.py", line 340, in main store = Store() File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/site-packages/pre_commit/store.py", line 51, in __init__ os.makedirs(self.directory, exist_ok=True) File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/os.py", line 223, in makedirs mkdir(name, mode) PermissionError: [Errno 13] Permission denied: '/home/gitpod/.cache/pre-commit'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/home/gitpod/mambaforge3/envs/pandas-dev/bin/pre-commit", line 11, in
sys.exit(main())
File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/site-packages/pre_commit/main.py", line 405, in main
raise AssertionError(
File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/contextlib.py", line 131, in exit
self.gen.throw(type, value, traceback)
File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/site-packages/pre_commit/error_handler.py", line 81, in error_handler
_log_and_exit(msg, ret_code, e, traceback.format_exc())
File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/site-packages/pre_commit/error_handler.py", line 31, in _log_and_exit
storedir = Store().directory
File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/site-packages/pre_commit/store.py", line 51, in init
os.makedirs(self.directory, exist_ok=True)
File "/home/gitpod/mambaforge3/envs/pandas-dev/lib/python3.8/os.py", line 223, in makedirs
mkdir(name, mode)
PermissionError: [Errno 13] Permission denied: '/home/gitpod/.cache/pre-commit'
(pandas-dev) gitpod > /workspace/pandas $

Though when I do pip install pre-commit , it says requirement satisfied.

pmeier · 2023-04-11T07:49:17Z

@ggold7046 Please make it a habit to wrap terminal output in triple backticks to get proper formatting. The traceback is painful to read the way you posted it.

The error you are facing has little to do with pre-commit. You seem to have no permissions to write to the /home/gitpod/.cache directory. I don't use GitPod so I can't help you there. However, if this a general thing, the pandas team might be interested in this report given that they promote GitPod as a way to develop on. Thus, all the tools should work. You can open a new issue detailing your problem.

For this PR though, you don't need pre-commit anymore. The CI error is formatting related, but this is nothing pre-commit, or rather the tools it invokes, can fix automatically. Fix the "Code Checks / Docstring validation" CI job and after that we should be done. The actual doc build failed to an unrelated issue. Hints:

The summary of the docstring is the first line that includes content.
RST "ignores" single line breaks and you need an actual blank line to separate two paragraphs.
You had this issue before and I suggested a solution to it in a comment that is now marked as "resolved".

ggold7046 · 2023-04-11T19:43:24Z

Hi @pmeier , both the code checks/pre-coomit and code checks/docstring validation have been passed at last. 😫 .

github-actions · 2023-04-12T05:32:01Z

Website preview of this PR available at: https://pandas.pydata.org/preview/51842/

pmeier

Awesome @ggold7046. Docstring looks good formatting wise and CI is happy as well. Now someone from the pandas team needs to review the content.

ggold7046 · 2023-04-12T13:16:22Z

Hi @MarcoGorelli , @datapythonista, @mroeschke could you have a review on this please ? I hope this time this PR gets merged.

MarcoGorelli

thank for working on this - got a minor comment, but this looks like it's close

can you also remove this line

pandas/ci/code_checks.sh

Line 88 in 8c7b8a4

pandas.Series.index \

please?

MarcoGorelli · 2023-04-12T15:07:05Z

pandas/core/series.py

+        doc="""
+        The index (axis labels) of the Series.
+
+        Get the index (row labels) of the Series.


I'm not sure what this sentence adds - why not move the paragraph starting with

The index of a Series is used to label and identify each element of the

to here?

to here?

I did not get it. Could you please tell me where to move ?

where I left the comment. i.e. instead of this "Get the index (row labels) of the Series." paragraph

Hi @MarcoGorelli , I tried to move that paragraph The index of a Series is used to label and identify each element of the to the first line replacing Get the index (row labels) of the Series., but it failed the CI. In the pandas documentation it is said that the first summary line should be a single meaning full line. And then an extending summary. So can we keep that single line as it is and can I revert back to the old commit ?

Not sure what you mean here @ggold7046. The summary, i.e.

The index (axis labels) of the Series.

is a single line. The CI fails because you again included trailing white space in the blank line.

ggold7046 · 2023-04-13T09:53:52Z

thank for working on this - got a minor comment, but this looks like it's close

can you also remove this line

pandas/ci/code_checks.sh

Line 88 in 8c7b8a4

pandas.Series.index \

please?

Hi @MarcoGorelli , I'm unable to edit this file in github page. The edit button is greyed out.

pmeier · 2023-04-13T10:40:00Z

I'm unable to edit this file in github page. The edit button is greyed out.

You should edit this file inside your PR. So judging from the comments above, inside the GitPod environment.

DOC add example of Series.index #51842

ggold7046 · 2023-04-13T15:21:52Z

@MarcoGorelli, @datapythonista, I have updated both the files. Could you please take a look and tell me if everything is fine ?

MarcoGorelli

Well done, thanks for sticking with this for so long

I'll leave open a bit in case Marc has other comments, and if not then we can merge

ggold7046 · 2023-04-14T13:16:00Z

Hi @datapythonista , could you please have a look at this PR so that it could be merged ?

datapythonista · 2023-04-16T20:44:41Z

Thanks @ggold7046 and the rest, very nice work.

ggold7046 · 2023-04-17T06:05:01Z

Hello @datapythonista , @MarcoGorelli thank for your time and support. And many many thanks for @pmeier for sticking with me for so long on this.

Update series.py DOC add example of Series.index #51842 . A newline between the text and the code is missing.

Update series.py

318c8da

Added the example section.

MarcoGorelli suggested changes Mar 9, 2023

View reviewed changes

MarcoGorelli changed the title ~~Update series.py~~ DOC add example of Series.index Mar 9, 2023

mroeschke added the Docs label Mar 9, 2023

ggold7046 added 3 commits March 10, 2023 19:12

Update series.py

8e0951a

Updated the docstring.

Update series.py

112928f

Updated the docstring.

Update series.py

5369605

New update.

datapythonista reviewed Mar 13, 2023

View reviewed changes

ggold7046 added 2 commits March 19, 2023 00:35

Update series.py

aa00a24

Update series.py

d3692a5

ggold7046 mentioned this pull request Mar 23, 2023

new contributor requesting guidance pmeier/pmeier#7

Closed

Update series.py

bd823b5

Merge branch 'main' into patch-1

4ab4d96

ggold7046 requested review from MarcoGorelli, datapythonista and pmeier April 1, 2023 19:15

pmeier suggested changes Apr 3, 2023

View reviewed changes

pandas/core/series.py Outdated Show resolved Hide resolved

pandas/core/series.py Outdated Show resolved Hide resolved

pandas/core/series.py Outdated Show resolved Hide resolved

pandas/core/series.py Outdated Show resolved Hide resolved

ggold7046 and others added 4 commits April 4, 2023 15:53

Update pandas/core/series.py

f3c576b

Co-authored-by: Philip Meier <[email protected]>

Update pandas/core/series.py

17da370

Co-authored-by: Philip Meier <[email protected]>

Update pandas/core/series.py

c5c8720

Co-authored-by: Philip Meier <[email protected]>

Update pandas/core/series.py

9c311ea

Co-authored-by: Philip Meier <[email protected]>

pmeier suggested changes Apr 4, 2023

View reviewed changes

pandas/core/series.py Outdated Show resolved Hide resolved

pandas/core/series.py Outdated Show resolved Hide resolved

ggold7046 requested a review from pmeier April 4, 2023 13:51

ggold7046 and others added 2 commits April 4, 2023 19:57

Update pandas/core/series.py

14bb848

Co-authored-by: Philip Meier <[email protected]>

Update pandas/core/series.py

ddb0fda

Co-authored-by: Philip Meier <[email protected]>

pmeier suggested changes Apr 4, 2023

View reviewed changes

pandas/core/series.py Outdated Show resolved Hide resolved

pmeier reviewed Apr 7, 2023

View reviewed changes

pandas/core/series.py Outdated Show resolved Hide resolved

pandas/core/series.py Show resolved Hide resolved

ggold7046 and others added 4 commits April 7, 2023 20:13

Update pandas/core/series.py

a1cf36d

Co-authored-by: Philip Meier <[email protected]>

Update pandas/core/series.py

62be40a

Co-authored-by: Philip Meier <[email protected]>

Update pandas/core/series.py

5c5dd5b

Co-authored-by: Philip Meier <[email protected]>

Update series.py

22da748

ggold7046 requested a review from pmeier April 7, 2023 18:26

ggold7046 added 2 commits April 11, 2023 19:02

Update series.py

ec0335e

Update series.py

87fccff

pmeier approved these changes Apr 12, 2023

View reviewed changes

MarcoGorelli suggested changes Apr 12, 2023

View reviewed changes

Update series.py

c98e6e2

ggold7046 requested a review from MarcoGorelli April 13, 2023 09:54

ggold7046 added 2 commits April 13, 2023 18:56

Update series.py

cb41a90

Update code_checks.sh

72c6ad2

DOC add example of Series.index #51842

MarcoGorelli approved these changes Apr 13, 2023

View reviewed changes

MarcoGorelli added this to the 2.1 milestone Apr 13, 2023

datapythonista merged commit aa4a039 into pandas-dev:main Apr 16, 2023

ggold7046 deleted the patch-1 branch April 17, 2023 06:01

mroeschke pushed a commit that referenced this pull request Apr 19, 2023

DOC add example of Series.index #51842 (#52780)

c7375d5

Update series.py DOC add example of Series.index #51842 . A newline between the text and the code is missing.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC add example of Series.index #51842

DOC add example of Series.index #51842

ggold7046 commented Mar 8, 2023

ggold7046 commented Mar 9, 2023

MarcoGorelli left a comment

ggold7046 commented Mar 9, 2023

datapythonista left a comment

datapythonista Mar 13, 2023

ggold7046 Mar 15, 2023

pmeier Mar 23, 2023

datapythonista Mar 13, 2023

datapythonista Mar 13, 2023

ggold7046 Mar 15, 2023

pmeier commented Mar 23, 2023

ggold7046 commented Apr 1, 2023

pmeier left a comment

pmeier left a comment

ggold7046 commented Apr 10, 2023 •

edited

Loading

pmeier commented Apr 11, 2023

ggold7046 commented Apr 11, 2023

github-actions bot commented Apr 12, 2023

pmeier left a comment

ggold7046 commented Apr 12, 2023 •

edited

Loading

MarcoGorelli left a comment

MarcoGorelli Apr 12, 2023

ggold7046 Apr 12, 2023

MarcoGorelli Apr 12, 2023

ggold7046 Apr 13, 2023

pmeier Apr 13, 2023

ggold7046 commented Apr 13, 2023

pmeier commented Apr 13, 2023

ggold7046 commented Apr 13, 2023 •

edited

Loading

MarcoGorelli left a comment

ggold7046 commented Apr 14, 2023

datapythonista commented Apr 16, 2023

ggold7046 commented Apr 17, 2023 •

edited

Loading

DOC add example of Series.index #51842

DOC add example of Series.index #51842

Conversation

ggold7046 commented Mar 8, 2023

ggold7046 commented Mar 9, 2023

MarcoGorelli left a comment

Choose a reason for hiding this comment

ggold7046 commented Mar 9, 2023

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmeier commented Mar 23, 2023

ggold7046 commented Apr 1, 2023

pmeier left a comment

Choose a reason for hiding this comment

pmeier left a comment

Choose a reason for hiding this comment

ggold7046 commented Apr 10, 2023 • edited Loading

pmeier commented Apr 11, 2023

ggold7046 commented Apr 11, 2023

github-actions bot commented Apr 12, 2023

pmeier left a comment

Choose a reason for hiding this comment

ggold7046 commented Apr 12, 2023 • edited Loading

MarcoGorelli left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ggold7046 commented Apr 13, 2023

pmeier commented Apr 13, 2023

ggold7046 commented Apr 13, 2023 • edited Loading

MarcoGorelli left a comment

Choose a reason for hiding this comment

ggold7046 commented Apr 14, 2023

datapythonista commented Apr 16, 2023

ggold7046 commented Apr 17, 2023 • edited Loading

ggold7046 commented Apr 10, 2023 •

edited

Loading

ggold7046 commented Apr 12, 2023 •

edited

Loading

ggold7046 commented Apr 13, 2023 •

edited

Loading

ggold7046 commented Apr 17, 2023 •

edited

Loading