DOC: add hidden IntervalIndex.str to prevent doc build warnings

[jorisvandenbossche]

@TomAugspurger @jreback This (should) fixes the warning related to the IntervalIndex.str, but, I was thinking we should maybe remove the full IntervalIndex class from the API docs?
I mean the class docstring, not the docstrings for the specific methods that are unique to the IntervalIndex

[jorisvandenbossche]

For the constructor, we could add it as IntervalIndex.__init__, but the problem is that Indexes currently don't have a __init__ defined to put the docstring.

It is just that adding the full IntervalIndex add another > 100 pages to the API docs (making the doc build longer and the docs heavier), which are mostly not needed

[codecov]

Codecov Report

Merging #16050 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #16050   +/-   ##
=======================================
  Coverage   90.79%   90.79%           
=======================================
  Files         156      156           
  Lines       50534    50534           
=======================================
  Hits        45883    45883           
  Misses       4651     4651

Flag	Coverage Δ
#multiple	88.56% <ø> (ø)	⬆️
#single	40.44% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2522efa...bfaefbc. Read the comment docs.

[jreback]

yes certainly fine to remove interval from docs

[jreback]

what if we take off all of the index autogenerated ones (but leave the specifically named method), eg. remove the first second but leave the 2nd? @jorisvandenbossche @TomAugspurger

.. _api.categoricalindex:

CategoricalIndex
----------------

.. autosummary::
   :toctree: generated/

   CategoricalIndex

Categorical Components
~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: generated/

   CategoricalIndex.codes
   CategoricalIndex.categories
   CategoricalIndex.ordered
   CategoricalIndex.rename_categories
   CategoricalIndex.reorder_categories
   CategoricalIndex.add_categories
   CategoricalIndex.remove_categories
   CategoricalIndex.remove_unused_categories
   CategoricalIndex.set_categories
   CategoricalIndex.as_ordered
   CategoricalIndex.as_unordered

[jorisvandenbossche]

@jreback yes, I think that is a good idea.
The only thing is that I would like to have a docstring for the class/constructor itself as well. That could be done for the __init__ method, if Index would have that. But maybe I can also see if I can get it working with sphinx to create a class docstring page without all attributes.

[TomAugspurger]

@jorisvandenbossche do you want me to take a look at this before the release? Just so I understand correctly.

But maybe I can also see if I can get it working with sphinx to create a class docstring page without all attributes

There is an exclude-members directive that works for autodoc. Let me check with autosummary. I worry a bit that our autosummary hack taken from numpy is ignoring the exclude-members directive.

[jorisvandenbossche]

What I was thinking was to make a separate class template for those classes for which we don't want all the members listed. But didn't think it fully through yet.

Another option is for now just add a manual autodoc page for IntervalIndex that is not autogenerated and does not included the overview of all methods/attributes (but not sure whether this prevents it being overwritten by the automatic generation step)

If you have time to look at this, certainly feel free!

[TomAugspurger]

@jorisvandenbossche I tried a few things to not autodoc everything on Index subclasses without success. Maybe just merge this as is for now. It'll remove the warnings at the least.

[TomAugspurger]

@jorisvandenbossche newer versions of numpydoc have a numpydoc_show_inherited_class_members flag that does pretty much what we want I think. The only issue is you don't get any fine-grained control, but maybe that's OK.

[jorisvandenbossche]

I am not sure we can use it in our case in general, as eg for DataFrame and Series we want all ones included, and not those that are inherited from NDFrame (but didn't try it, so don't know whether it makes sense).

[TomAugspurger]

Oh yeah, of course. I was only thinking of public things that inherit from other public things :/

I'll see how hard it is to extend numpydoc to give us more control over what goes into autosummary. Not before the release though. Merge this in the meantime?

[jorisvandenbossche]

Closed by alternative PR #16221