Remove unnecessary templates

Author: vyasr

doc/source/conf.py

@@ -696,45 +696,6 @@ 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 [
@@ -787,7 +748,6 @@ 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,25 +73,20 @@ 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.
-
-  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.
+  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.
 
   Every method should be included in a ``toctree`` in one of the documentation files in
-  ``doc/source/reference``, else Sphinx
-  will emit a warning.
+  ``doc/source/reference``, otherwise 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,13 +104,11 @@ values.
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    arrays.ArrowExtensionArray
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    ArrowDtype
 
@@ -233,13 +231,11 @@ 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
 
@@ -299,7 +295,6 @@ A collection of :class:`Timedelta` may be stored in a :class:`TimedeltaArray`.
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    arrays.TimedeltaArray
 
@@ -361,13 +356,11 @@ 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
 
@@ -404,13 +397,11 @@ 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
 
@@ -449,13 +440,11 @@ 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
@@ -474,13 +463,11 @@ Nullable float
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    arrays.FloatingArray
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    Float32Dtype
    Float64Dtype
@@ -497,7 +484,6 @@ a :class:`CategoricalDtype`.
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    CategoricalDtype
 
@@ -511,7 +497,6 @@ Categorical data can be stored in a :class:`pandas.Categorical`
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    Categorical
 
@@ -561,13 +546,11 @@ 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
 
@@ -586,14 +569,12 @@ 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
 
@@ -612,13 +593,11 @@ 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,7 +21,6 @@ objects.
 
 .. autosummary::
    :toctree: api/
-   :template: autosummary/class_without_autosummary.rst
 
    api.extensions.ExtensionArray
    arrays.NumpyExtensionArray

doc/source/reference/groupby.rst

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

doc/source/reference/indexing.rst

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

doc/source/reference/offset_frequency.rst

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