DOC: make RST files conform to pandas token usage
State: closed

See also: #32316

- [x] closes #32316
- [x] tests added / passed
- [x] passes `black pandas`
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


In #36845 the RST files were updated to normalize usage of the word "pandas". The following tokens were replaced:
+ \`pandas\`
+ \`\`pandas\`\`
+ \*pandas\*
+ \*\*pandas\*\*
+ Pandas

In that PR, I wrongly said that I caught all patterns. I was wrong, and this PR address that (my apologies). 

#### Misc Note

I'm also working on a rule for `code_checks.sh` to catch this in the future. I have the logic of the rule, but I'm struggling to get it to output nicely in such a way that it conforms with the rest of the rules in `code_checks.sh`. I want to leave this information here in case someone has any ideas I can bounce of off, or in case anyone else wants to try their hand at this. I could be spinning my wheels there for awhile and don't want it to hold up getting these changes in.

I used the following rule to find the remaining cases:
```shell
    MSG='Check doc/source RST files which format pandas incorrectly'; echo $MSG
    invgrep -R --include=*.rst -Poz '((\*|`)+)pandas\2|((((\.\. code-block:: ipython\s+)(\s +[^\n]*)+)|.\.\ [^\n]+https?[^\n]+|(`+).*\s+<https?[^\n]+>\8(__)?|`.*`_+\s+~+|.*:ref:`.*`)(*SKIP)(?!)|\bPandas\b(?!-))' doc/source/ | sed 's/\x0/\n/g'
    RET=$(($RET + $?)) ; echo $MSG "DONE"
```

This finds easily identifiable formatting errors (\`\`pandas\`\`, for example), but it also respects article titles and code examples in an RST `code-block`s. It uses `grep -v` to get all text on a single line, but that causes error messages to lose the line number of the file that the error occurred on (everything in file `foo.rst` is reported to have happened on line 1). Because of this I'm not including the regex in this PR. If anyone is interested in giving me pointers on getting that bit fixed, or even taking my idea and running with it themselves, please do so.

Edit:

Because its desired to retain \`\`pandas\`\` in some places where it contextually make sense, regex won't be able to capture such uses. The above regex can instead be:
```shell
    MSG='Check doc/source RST files which format pandas incorrectly'; echo $MSG
    invgrep -R --include=*.rst -Poz '(\*+|`)pandas\1|((((\.\. code-block:: ipython\s+)(\s +[^\n]*)+)|.\.\ [^\n]+https?[^\n]+|(`+).*\s+<https?[^\n]+>\7(__)?|`.*`_+\s+~+|.*:ref:`.*`)(*SKIP)(?!)|\bPandas\b(?!-))' doc/source/ | sed 's/\x0/\n/g'
    RET=$(($RET + $?)) ; echo $MSG "DONE"
```

which will ignore \`\`pandas\`\` but catch \`pandas\`


Labels:
name: Docs
name: Stale

Comments:
> and it should be `pandas` (double-backticks)

That's not what we have been doing in a bunch of previous PRs, though. 

But, I would say we shouldn't convert *all* occurrences of "`pandas`" to "pandas". IMO, it if it clearly about the *package* (and not the project in general), it is fine to keep using `pandas` in some places, instead of having a hard rule.
> But, I would say we shouldn't convert _all_ occurrences of "`pandas`" to "pandas". IMO, it if it clearly about the _package_ (and not the project in general), it is fine to keep using `pandas` in some places, instead of having a hard rule.

Noted. I'll update my PR to change this.
I added \`\`pandas\`\` back into the docs where I think it makes sense based on context. Its kind of subjective, so I'd appreciate feedback on 5d9b3344698392a40292ca561063467a60345028 and the remaining diffs in the PR.
can you merge master and ping on green
This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
closing as stale if you want to continue, pls open a new PR.