DOC: Harmonize column selection to bracket notation

[katrinleinweber]

As suggested by @tdpetrou. If there is agreement about not presenting the dot notation to access columns in the docu, please let me know and I'll then check the rest of the docu.

• [~] closes #xxxx
• [~] tests added / passed
• [~] passes black pandas
• [~] passes git diff upstream/master -u -- "*.py" | flake8 --diff
• passes git diff upstream/master -u -- "*.rst" | flake8-rst --diff
• [~] whatsnew entry

[TomAugspurger]

+1 to generally using getitem in the docs, other than the section describing dot access.

Can we think of a way to lint this, to ensure that we don’t regress on it in the future? I’m struggling to think of an easy way. A slightly harder way is to check for dot access of names that are in the columns with a python program run on the docs.

[WillAyd]

I'd be +1 for making this change comprehensively

[katrinleinweber]

I will not be able to write python code to detect those occasions. Using df(.?)\.([A-D])(\W) for now and

• checking the context.

Shall I also update old whatsnew/*.rst files?

[WillAyd]

I think ignore old whatsnews for now - we usually don't go back and change them

[katrinleinweber]

OK, I hope I didn't overlook any of these changes' context to explicitly mention "dot" notation/access/attribute.

[katrinleinweber]

In order to add a whatsnew entry, shall I re-point this PR to branch 0.25.x? If yes, I would also add a Documentation section there, since I'm not sure into which of the pre-defined sections to put a summary of this change otherwise.

[WillAyd]

Don’t need a whatsnew for doc changes. Also can just point to master - We can back port to 0.25.1 if needed (though not sure we would for this)

[TomAugspurger]

No need for back port.

[katrinleinweber]

OK :-) Anything else to do here, then besides fixing those CI errors? Maybe a note recommending [ bracket ] notation (or summarising its advantages)?

The indexing operator ``[]`` provides a superset of the attribute operator ``.``,
such as the ability to index column names using a variable, or column names
that are the same as DataFrame methods, or contain spaces. Therefore, it is
recommended and presented here preferably.

[katrinleinweber]

I'll run the checks locally with flake8-rst doc/source/ --filename="*.rst" --format="default" to debug all these issues.

[jreback]

no objection to most of these changes, but some need to be reverted as indicated

[jorisvandenbossche]

Thanks! Some additional comments

[WillAyd]

lgtm

[TomAugspurger]

Thanks @katrinleinweber!

[katrinleinweber]

You're welcome! Thanks to you though, for agreeing with this & for merging :-)