DOC/API: provide a doc matrix of all indexing accessors and behaviors

[jreback]

related #5420

ML issue: https://groups.google.com/forum/#!topic/pydata/Ke8kntiPHqw

existing tests here (and tests/test_frame.py, test_multilevel.py)
https://github.com/pydata/pandas/blob/master/pandas/tests/test_indexing.py

• create new top-level advanced indexing tab (move hierarchical and sections below here)
• add an indexer matrix (generated from a function), which can document a cross of the indexers with the index types and accessors, e.g. something like this (the values should be filled in with maybe a code of somesort, e.g. Y for supported, NI for not-implemented, nan for not-applicable, KeyError/IndexError if raises

In [31]: from itertools import product

In [35]: index = MultiIndex.from_tuples([ (typ,indexer) for typ,indexer in product(['MultiIndex','DateTimeIndex','FloatIndex','Int64Index','mixed_labels'],['iloc','loc','ix','[]','xs']) ])

In [36]: columns = ['scalar_label_in_bounds','oob_scalar_label','scalar_position','oob_scalar_position','list_of_positions','list_of_positions_some_oob','list_of_labels','list_of_labels_some_oob','slice_of_positions','slice_of_labels','boolean_indexer']

In [37]: DataFrame(np.nan,index=index,columns=columns)
Out[37]: 
                    scalar_label_in_bounds  oob_scalar_label  scalar_position  oob_scalar_position  list_of_positions  list_of_positions_some_oob  list_of_labels  list_of_labels_some_oob  slice_of_positions  slice_of_labels  boolean_indexer
MultiIndex    iloc                     NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              loc                      NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              ix                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              []                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              xs                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
DateTimeIndex iloc                     NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              loc                      NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              ix                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              []                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              xs                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
FloatIndex    iloc                     NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              loc                      NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              ix                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              []                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              xs                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
Int64Index    iloc                     NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              loc                      NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              ix                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              []                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              xs                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
mixed_labels  iloc                     NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              loc                      NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              ix                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              []                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN
              xs                       NaN               NaN              NaN                  NaN                NaN                         NaN             NaN                      NaN                 NaN              NaN              NaN

[jtratner]

+1

an alternative is to deprecate ix and xs (documentation-wise ) and declare loc,.iloc
to be the "it" from now on. That's how I think of them ever since 0.11.
We have to support ix and xs for legacy code, but we're not required to advocate them
to new users. Doing that will only make a difference to the underlying issue if we can keep loc and iloc
sane going forward, though. #6249

I'm going to coin the term "convenience creep" here, for future use.
Hell, for past use: #5655 , #5874, #5954.

[datapythonista]

I don't think this is as useful since .ix is already deprecated, there are discussions on deprecating .xs and the approach is to make indexing simpler in general. Closing.