DOC add example of Series.index
State: closed

Added the example section.

- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
- [ ] [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:
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.
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. 
Online doc preview for this PR is here: https://pandas.pydata.org/preview/51842/docs/reference/api/pandas.Series.index.html#pandas.Series.index
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. 

![pandas1](https://user-images.githubusercontent.com/98327736/229309689-6a721fa7-3381-484f-b797-bbc18e871724.png)

![pandas2](https://user-images.githubusercontent.com/98327736/229309701-0fab89fd-95da-47b0-b432-f7f7f72492d1.png)

> [Here](https://pandas.pydata.org/docs/development/contributing.html#id14) is documentation on how to do that automatically.

Hi @pmeier. this link points to [https://pandas.pydata.org/docs/development/contributing_codebase.html#contributing-pre-commit](url) , which states that it will only check, but it will not rectify automatically. 
I don't see anything like that in the documentation. In fact, `ruff` (the failing linter) actually reports that it fixed the issues: https://github.com/pandas-dev/pandas/actions/runs/4632004601/jobs/8195545816?pr=51842#step:4:128

Here is the exact command the CI is running: https://github.com/pandas-dev/pandas/actions/runs/4632004601/jobs/8195545816?pr=51842#step:4:103

```
pre-commit run --show-diff-on-failure --color=always --verbose --all-files
```

Doing so, should fix all issues that are automatically fixable.

Just to show what is happening over and over: look at the latest commit you send fc3c0ed3449ead2669a4b6ac399c3bf4656c4089. Do you see all the whitespace you added? As I told you in https://github.com/pandas-dev/pandas/pull/51842#discussion_r1156324126, it is a good idea to configure your editor to show whitespace to avoid errors like that.


/preview
Website preview of this PR available at: https://pandas.pydata.org/preview/51842/
This is the error I'm getting while running the `pre-commit install` command in gitpod.
<details>
<summary>Error installing pre-commit</summary>
<br>
(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 <module>
    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 $ 
</details>

Though when I do `pip install pre-commit` , it says requirement satisfied.
@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: 

1. The summary of the docstring is the first line that includes content.
2. RST "ignores" single line breaks and you need an actual blank line to separate two paragraphs.
3. You had this issue before and I suggested a solution to it in a comment that is now marked as "resolved".
Hi @pmeier , both the `code checks/pre-coomit` and `code checks/docstring validation` have been passed at last. :tired_face:  .
Website preview of this PR available at: https://pandas.pydata.org/preview/51842/
Hi @MarcoGorelli , @datapythonista, @mroeschke  could you have a review on this please ? I hope this time this PR gets merged. 
> thank for working on this - got a minor comment, but this looks like it's close
> 
> can you also remove this line
> 
> https://github.com/pandas-dev/pandas/blob/8c7b8a4f3eaf4aef90c300baa9a2337323f7a12b/ci/code_checks.sh#L88
> 
> please?

Hi @MarcoGorelli , I'm unable to edit this file in github page. The edit button is greyed out. 
> 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.
@MarcoGorelli, @datapythonista, I have updated both the files. Could you please take a look and tell me if everything is fine ?
Hi @datapythonista , could you please have a look at this PR so that it could be merged ? 
Thanks @ggold7046 and the rest, very nice work.
Hello @datapythonista , @MarcoGorelli thank for your time and support. And many many thanks for @pmeier for sticking with me for so long on this.