Add notes on contributing

doc/source/api.rst

@@ -344,7 +344,6 @@ Binary operator functions
 
    Series.add
    Series.sub
-   Series.subtract
    Series.mul
    Series.div
    Series.truediv
@@ -715,20 +714,21 @@ a :class:`pandas.api.types.CategoricalDtype`.
    api.types.CategoricalDtype.categories
    api.types.CategoricalDtype.ordered
 
-Categorical data can be stored in a :class:``pandas.Categorical``
+Categorical data can be stored in a :class:`pandas.Categorical`
 
 .. autosummary::
    :toctree: generated/
+   :template: autosummary/class_without_autosummary.rst
 
    Categorical
 
-The following two ``Categorical`` constructors are considered API but should only be used when
-adding ordering information or special categories is need at creation time of the categorical data:
+
+The alternative :ref:`Categorical.from_codes` constructor can be used when you
+have the categories and integer codes already:
 
 .. autosummary::
    :toctree: generated/
 
-   Categorical.categories
    Categorical.from_codes
 
 The dtype information is available on the ``Categorical``
@@ -2617,6 +2617,7 @@ Scalar introspection
    generated/pandas.Series.ix
    generated/pandas.Series.notnull.rst
    generated/pandas.Series.set_value
+   generated/pandas.Series.subtract
 
    generated/pandas.Series.cat
    generated/pandas.Series.dt
@@ -2625,15 +2626,6 @@ Scalar introspection
    generated/pandas.Timestamp.offset
    generated/pandas.Timestamp.to_datetime
 
-   generated/pandas.Categorical.base.rst
-   generated/pandas.Categorical.itemsize.rst
-   generated/pandas.Categorical.labels.rst
-   generated/pandas.Categorical.nbytes.rst
-   generated/pandas.Categorical.ndim.rst
-   generated/pandas.Categorical.shape.rst
-   generated/pandas.Categorical.size.rst
-   generated/pandas.Categorical.T.rst
-
    generated/pandas.DataFrame.subtract
    generated/pandas.DataFrame.multiply
    generated/pandas.DataFrame.divide

doc/source/contributing.rst

@@ -317,6 +317,27 @@ Some other important things to know about the docs:
   doc build. This approach means that code examples will always be up to date,
   but it does make the doc building a bit more complex.
 
+- Our API documentation in ``doc/source/api.rst`` houses 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 autogenerate a page for public method and attribute on the
+     class. The class should include the regular ``Parameters`` section, but
+     need not include ``Attributes`` or ``Methods``. Those sections will be
+     automatically added to the rendered documentation by numpydoc.
+
+  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 ``api.rst``, else Sphinx
+  will emit a warning.
+
 .. note::
 
     The ``.rst`` files are used to automatically generate Markdown and HTML versions

pandas/core/categorical.py

@@ -194,6 +194,11 @@ class Categorical(PandasObject):
 
         .. versionadded:: 0.21.0
 
+    Methods
+    -------
+    from_codes
+    __array__
+
     Raises
     ------
     ValueError

pandas/core/indexes/category.py

@@ -52,10 +52,6 @@ class CategoricalIndex(Index, accessor.PandasDelegate):
     categories
     ordered
 
-    See Also
-    --------
-    Categorical, Index
-
     Methods
     -------
     rename_categories
@@ -67,6 +63,10 @@ class CategoricalIndex(Index, accessor.PandasDelegate):
     as_ordered
     as_unordered
     map
+
+    See Also
+    --------
+    Categorical, Index
     """
 
     _typ = 'categoricalindex'