Revert "Remove unnecessary templates"

This reverts commit 80b6bf9.

Author: vyasr

doc/source/conf.py

@@ -696,6 +696,45 @@ def remove_flags_docstring(app, what, name, obj, options, lines):
         del lines[:]
 
 
+def process_class_docstrings(app, what, name, obj, options, lines):
+    """
+    For those classes for which we use ::
+
+    :template: autosummary/class_without_autosummary.rst
+
+    the documented attributes/methods have to be listed in the class
+    docstring. However, if one of those lists is empty, we use 'None',
+    which then generates warnings in sphinx / ugly html output.
+    This "autodoc-process-docstring" event connector removes that part
+    from the processed docstring.
+
+    """
+    if what == "class":
+        joined = "\n".join(lines)
+
+        templates = [
+            """.. rubric:: Attributes
+
+.. autosummary::
+   :toctree:
+
+   None
+""",
+            """.. rubric:: Methods
+
+.. autosummary::
+   :toctree:
+
+   None
+""",
+        ]
+
+        for template in templates:
+            if template in joined:
+                joined = joined.replace(template, "")
+        lines[:] = joined.split("\n")
+
+
 _BUSINED_ALIASES = [
     "pandas.tseries.offsets." + name
     for name in [
@@ -748,6 +787,7 @@ def rstjinja(app, docname, source):
 def setup(app):
     app.connect("source-read", rstjinja)
     app.connect("autodoc-process-docstring", remove_flags_docstring)
+    app.connect("autodoc-process-docstring", process_class_docstrings)
     app.connect("autodoc-process-docstring", process_business_alias_docstrings)
     app.add_autodocumenter(AccessorDocumenter)
     app.add_autodocumenter(AccessorAttributeDocumenter)

doc/source/development/contributing_documentation.rst

@@ -73,20 +73,25 @@ Some other important things to know about the docs:
 
 * Our API documentation files in ``doc/source/reference`` house the auto-generated
   documentation from the docstrings. For classes, there are a few subtleties
-  around controlling which methods and attributes have pages auto-generated. The
-  default autosummary template will generate pages for all public methods and
-  attributes of classes. ``numpydoc`` will also automatically generate an
-  ``Attributes`` and ``Methods`` section for the class, leading to a redundant
-  specification. To prevent this duplication, we have a custom autosummary
-  template ``_templates/autosummary/class.rst`` that will generate class pages
-  without any method or attribute documentation. 
-
-  For some classes we only want to document a subset of APIs. For those, the
-  you should include an ``Attributes`` and ``Methods`` section in the class
-  docstring. See ``CategoricalIndex`` for an example.
+  around controlling which methods and attributes have pages auto-generated.
+
+  We have two autosummary templates for classes.
+
+  1. ``_templates/autosummary/class.rst``. Use this when you want to
+     automatically generate a page for every public method and attribute on the
+     class. The ``Attributes`` and ``Methods`` sections will be automatically
+     added to the class' rendered documentation by numpydoc. See ``DataFrame``
+     for an example.
+
+  2. ``_templates/autosummary/class_without_autosummary``. Use this when you
+     want to pick a subset of methods / attributes to auto-generate pages for.
+     When using this template, you should include an ``Attributes`` and
+     ``Methods`` section in the class docstring. See ``CategoricalIndex`` for an
+     example.
 
   Every method should be included in a ``toctree`` in one of the documentation files in
-  ``doc/source/reference``, otherwise Sphinx will emit a warning.
+  ``doc/source/reference``, else Sphinx
+  will emit a warning.
 
 The utility script ``scripts/validate_docstrings.py`` can be used to get a csv
 summary of the API documentation. And also validate common errors in the docstring

doc/source/reference/arrays.rst

@@ -104,11 +104,13 @@ values.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.ArrowExtensionArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    ArrowDtype
 
@@ -231,11 +233,13 @@ If the data are timezone-aware, then every value in the array must have the same
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.DatetimeArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    DatetimeTZDtype
 
@@ -295,6 +299,7 @@ A collection of :class:`Timedelta` may be stored in a :class:`TimedeltaArray`.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.TimedeltaArray
 
@@ -356,11 +361,13 @@ Every period in a :class:`arrays.PeriodArray` must have the same ``freq``.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.PeriodArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    PeriodDtype
 
@@ -397,11 +404,13 @@ A collection of intervals may be stored in an :class:`arrays.IntervalArray`.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.IntervalArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    IntervalDtype
 
@@ -440,11 +449,13 @@ pandas provides this through :class:`arrays.IntegerArray`.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.IntegerArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    Int8Dtype
    Int16Dtype
@@ -463,11 +474,13 @@ Nullable float
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.FloatingArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    Float32Dtype
    Float64Dtype
@@ -484,6 +497,7 @@ a :class:`CategoricalDtype`.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    CategoricalDtype
 
@@ -497,6 +511,7 @@ Categorical data can be stored in a :class:`pandas.Categorical`
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    Categorical
 
@@ -546,11 +561,13 @@ be stored efficiently as a :class:`arrays.SparseArray`.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.SparseArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    SparseDtype
 
@@ -569,12 +586,14 @@ we recommend using :class:`StringDtype` (with the alias ``"string"``).
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.StringArray
    arrays.ArrowStringArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    StringDtype
 
@@ -593,11 +612,13 @@ with a bool :class:`numpy.ndarray`.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    arrays.BooleanArray
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    BooleanDtype
    NA

doc/source/reference/extensions.rst

@@ -21,6 +21,7 @@ objects.
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    api.extensions.ExtensionArray
    arrays.NumpyExtensionArray

doc/source/reference/groupby.rst

@@ -29,6 +29,7 @@ Indexing, iteration
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    Grouper
 

doc/source/reference/indexing.rst

@@ -163,6 +163,7 @@ Numeric Index
 -------------
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    RangeIndex
 
@@ -183,6 +184,7 @@ CategoricalIndex
 ----------------
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    CategoricalIndex
 
@@ -217,6 +219,7 @@ IntervalIndex
 -------------
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    IntervalIndex
 
@@ -251,6 +254,7 @@ MultiIndex
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    MultiIndex
 
@@ -317,6 +321,7 @@ DatetimeIndex
 -------------
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    DatetimeIndex
 
@@ -402,6 +407,7 @@ TimedeltaIndex
 --------------
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    TimedeltaIndex
 
@@ -443,6 +449,7 @@ PeriodIndex
 -----------
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    PeriodIndex
 

doc/source/reference/offset_frequency.rst

@@ -56,6 +56,7 @@ Alias:
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    BDay
 
@@ -142,6 +143,7 @@ Alias:
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    CDay
 
@@ -298,6 +300,7 @@ Alias:
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    BMonthEnd
 
@@ -341,6 +344,7 @@ Alias:
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    BMonthBegin
 
@@ -384,6 +388,7 @@ Alias:
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    CBMonthEnd
 
@@ -431,6 +436,7 @@ Alias:
 
 .. autosummary::
    :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
 
    CBMonthBegin