DOC: Make section title capitalization consistent

[datapythonista]

At the moment we've got a mix of capitalization formats in the title sections of our docs. For example, in the first level of the TOC tree in http://dev.pandas.io/ we've got (not the second word first letter, s lower case vs G upper case):

• Getting started
• User Guide

And this happens all across the documentation. I think it makes more sense to just capitalize the first letter of the first word, like in Getting started. More a personal preference than any objective reason, but looks simpler, more standard, and we avoid things like pandas Ecosystem which doesn't look really great to me.

CC: @TomAugspurger @jorisvandenbossche

[jorisvandenbossche]

I think that is due to having a mix of American vs European style contributors :)

I suppose you propose that for all levels of the documentation?
I personally also favor the "This is a nice title" (sentence case) instead of "This is a Nice Title" style (title case).

Something in between is also possible: eg chapters use title case, and further subsections use sentence case

[datapythonista]

I propose at all levels, I think the main value is in being consistent, and the simpler it's our standard, the easier for everyone.

Mainly concerned on the bad impression that gives the home page with the mix atm. Marked as "good first issue" some someone can pick this up.

[HolgerSpernau]

Hi, how could I support on that topic? Could you explain a bit? Where to find the data? Thanks.

[datapythonista]

You have info in the contributing to pandas page: https://dev.pandas.io/development/contributing.html

Once you clone the repo locally, the idea is to go to the pages in doc/source and fix the capitalization of the title. Here you have an example to be changed: https://github.com/pandas-dev/pandas/blame/master/doc/source/user_guide/index.rst#L6

[datapythonista]

My points to defend this:

• Consistency across all documentation headers
• It's much easier to keep consistency if the standard is simpler (and title case is somehow ambiguous if you're not a linguist I'd say Implement one Thing vs Implement One Thing)
• I understand that title case gives some emphasis, but the documentation renders titles in bigger letters and bold, so doesn't seem that needed to me
• Given that we prefer pandas in lowercase, title case makes some titles quite ugly in my opinion pandas Ecosystem is the main one (in the top level).

[jreback]

agree with the consistency theme.

what do other projects do?

I actually like the keyword capitlization, maybe better to just make it consistent?

[datapythonista]

I check related projects (numpy, matplotlib, scikit-learn and not sure if any other), and they have a mix, like us now.

I'm happy as far as there is consistency. But I think it makes things easier to keep consistency with a simpler rule, I really don't want to discuss in reviews if we a specific word in the middle of the sentence is an article or not and should be capitalized. I think we have all better things to do. And I don't think any of the options has an actual advantage per se, just a question of personal preference.

[jorisvandenbossche]

Was also looking at some projects, and indeed they all have somewhat an inconsistent mix. But I find that the majority of the titles seems to be sentence case, not title case. See eg https://docs.scipy.org/doc/numpy/reference/index.html

[jorisvandenbossche]

Even with a simple rule as "always bsentence case", there will be a set of words that we want to capitalize. Some obvious ones such as DataFrame and Series. And some less clear ones such as Timestamp, Accessor, Groupby ?

[jreback]

ok, let go with your plan and see how it looks then. I agree a simpler rule is probably best.

[datapythonista]

I'll also create an issue to add validation for it, with sentence case I think it shouldn't be difficult, with just a list of words that need to be capitalized, as @jorisvandenbossche said.

[datapythonista]

Created #26941 for the validation.