DOC: some doc fixes (#17913)

* fix/update examples in user guide

* fix some docstrings

* don't include all methods/attributes of CategoricalDtype

* additional fix

Author: jorisvandenbossche

doc/source/api.rst

@@ -649,6 +649,7 @@ The dtype of a ``Categorical`` can be described by a :class:`pandas.api.types.Ca
 
 .. autosummary::
    :toctree: generated/
+   :template: autosummary/class_without_autosummary.rst
 
    api.types.CategoricalDtype
 

doc/source/basics.rst

@@ -1205,7 +1205,7 @@ You may also use ``reindex`` with an ``axis`` keyword:
 
 .. ipython:: python
 
-   df.reindex(index=['c', 'f', 'b'], axis='index')
+   df.reindex(['c', 'f', 'b'], axis='index')
 
 Note that the ``Index`` objects containing the actual axis labels can be
 **shared** between objects. So if we have a Series and a DataFrame, the

doc/source/indexing.rst

@@ -1509,18 +1509,6 @@ default value.
    s.get('a')               # equivalent to s['a']
    s.get('x', default=-1)
 
-The :meth:`~pandas.DataFrame.select` Method
--------------------------------------------
-
-Another way to extract slices from an object is with the ``select`` method of
-Series, DataFrame, and Panel. This method should be used only when there is no
-more direct way.  ``select`` takes a function which operates on labels along
-``axis`` and returns a boolean.  For instance:
-
-.. ipython:: python
-
-   df.select(lambda x: x == 'A', axis=1)
-
 The :meth:`~pandas.DataFrame.lookup` Method
 -------------------------------------------
 

doc/source/missing_data.rst

@@ -196,7 +196,7 @@ With ``sum`` or ``prod`` on an empty or all-``NaN`` ``Series``, or columns of a
 
 .. ipython:: python
 
-   s = Series([np.nan])
+   s = pd.Series([np.nan])
 
    s.sum()
 

doc/sphinxext/numpydoc/numpydoc.py

@@ -45,7 +45,7 @@ def mangle_docstrings(app, what, name, obj, options, lines,
     # PANDAS HACK (to remove the list of methods/attributes for Categorical)
     no_autosummary = [".Categorical", "CategoricalIndex", "IntervalIndex",
                       "RangeIndex", "Int64Index", "UInt64Index",
-                      "Float64Index", "PeriodIndex"]
+                      "Float64Index", "PeriodIndex", "CategoricalDtype"]
     if what == "class" and any(name.endswith(n) for n in no_autosummary):
         cfg['class_members_list'] = False
 

pandas/_libs/period.pyx

@@ -833,9 +833,9 @@ cdef class _Period(object):
 
         Parameters
         ----------
-        freq : string or DateOffset, default is 'D' if self.freq is week or
-               longer and 'S' otherwise
-            Target frequency
+        freq : string or DateOffset
+            Target frequency. Default is 'D' if self.freq is week or
+            longer and 'S' otherwise
         how: str, default 'S' (start)
             'S', 'E'. Can be aliased as case insensitive
             'Start', 'Finish', 'Begin', 'End'
@@ -1067,46 +1067,48 @@ cdef class _Period(object):
         | ``%%``    | A literal ``'%'`` character.   |       |
         +-----------+--------------------------------+-------+
 
-        .. note::
-
-            (1)
-                The ``%f`` directive is the same as ``%y`` if the frequency is
-                not quarterly.
-                Otherwise, it corresponds to the 'fiscal' year, as defined by
-                the :attr:`qyear` attribute.
-
-            (2)
-                The ``%F`` directive is the same as ``%Y`` if the frequency is
-                not quarterly.
-                Otherwise, it corresponds to the 'fiscal' year, as defined by
-                the :attr:`qyear` attribute.
-
-            (3)
-                The ``%p`` directive only affects the output hour field
-                if the ``%I`` directive is used to parse the hour.
-
-            (4)
-                The range really is ``0`` to ``61``; this accounts for leap
-                seconds and the (very rare) double leap seconds.
-
-            (5)
-                The ``%U`` and ``%W`` directives are only used in calculations
-                when the day of the week and the year are specified.
-
-        .. rubric::  Examples
-
-            >>> a = Period(freq='Q@JUL', year=2006, quarter=1)
-            >>> a.strftime('%F-Q%q')
-            '2006-Q1'
-            >>> # Output the last month in the quarter of this date
-            >>> a.strftime('%b-%Y')
-            'Oct-2005'
-            >>>
-            >>> a = Period(freq='D', year=2001, month=1, day=1)
-            >>> a.strftime('%d-%b-%Y')
-            '01-Jan-2006'
-            >>> a.strftime('%b. %d, %Y was a %A')
-            'Jan. 01, 2001 was a Monday'
+        Notes
+        -----
+
+        (1)
+            The ``%f`` directive is the same as ``%y`` if the frequency is
+            not quarterly.
+            Otherwise, it corresponds to the 'fiscal' year, as defined by
+            the :attr:`qyear` attribute.
+
+        (2)
+            The ``%F`` directive is the same as ``%Y`` if the frequency is
+            not quarterly.
+            Otherwise, it corresponds to the 'fiscal' year, as defined by
+            the :attr:`qyear` attribute.
+
+        (3)
+            The ``%p`` directive only affects the output hour field
+            if the ``%I`` directive is used to parse the hour.
+
+        (4)
+            The range really is ``0`` to ``61``; this accounts for leap
+            seconds and the (very rare) double leap seconds.
+
+        (5)
+            The ``%U`` and ``%W`` directives are only used in calculations
+            when the day of the week and the year are specified.
+
+        Examples
+        --------
+
+        >>> a = Period(freq='Q@JUL', year=2006, quarter=1)
+        >>> a.strftime('%F-Q%q')
+        '2006-Q1'
+        >>> # Output the last month in the quarter of this date
+        >>> a.strftime('%b-%Y')
+        'Oct-2005'
+        >>>
+        >>> a = Period(freq='D', year=2001, month=1, day=1)
+        >>> a.strftime('%d-%b-%Y')
+        '01-Jan-2006'
+        >>> a.strftime('%b. %d, %Y was a %A')
+        'Jan. 01, 2001 was a Monday'
         """
         base, mult = get_freq_code(self.freq)
         return period_format(self.ordinal, base, fmt)

pandas/core/frame.py

@@ -2634,7 +2634,7 @@ def assign(self, **kwargs):
         Notes
         -----
         For python 3.6 and above, the columns are inserted in the order of
-        **kwargs. For python 3.5 and earlier, since **kwargs is unordered,
+        \*\*kwargs. For python 3.5 and earlier, since \*\*kwargs is unordered,
         the columns are inserted in alphabetical order at the end of your
         DataFrame.  Assigning multiple columns within the same ``assign``
         is possible, but you cannot reference other columns created within
@@ -2975,8 +2975,8 @@ def rename(self, mapper=None, index=None, columns=None, axis=None,
 
         ``DataFrame.rename`` supports two calling conventions
 
-        * ``(index=index_mapper, columns=columns_mapper, ...)
-        * ``(mapper, axis={'index', 'columns'}, ...)
+        * ``(index=index_mapper, columns=columns_mapper, ...)``
+        * ``(mapper, axis={'index', 'columns'}, ...)``
 
         We *highly* recommend using keyword arguments to clarify your
         intent.

pandas/core/generic.py

@@ -846,8 +846,8 @@ def _validate_axis_style_args(self, arg, arg_name, axes,
 
         ``DataFrame.rename`` supports two calling conventions
 
-        * ``(index=index_mapper, columns=columns_mapper, ...)
-        * ``(mapper, axis={'index', 'columns'}, ...)
+        * ``(index=index_mapper, columns=columns_mapper, ...)``
+        * ``(mapper, axis={'index', 'columns'}, ...)``
 
         We *highly* recommend using keyword arguments to clarify your
         intent.
@@ -2875,8 +2875,8 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
 
         ``DataFrame.reindex`` supports two calling conventions
 
-        * ``(index=index_labels, columns=column_labels, ...)
-        * ``(labels, axis={'index', 'columns'}, ...)
+        * ``(index=index_labels, columns=column_labels, ...)``
+        * ``(labels, axis={'index', 'columns'}, ...)``
 
         We *highly* recommend using keyword arguments to clarify your
         intent.