DOC: update api.rst for Categorical accessors / methods

[jreback]

we have a Categorical section, but this mainly describes .cat. Maybe split this out into a separate section to document the actual Categorical methods / accessors (even though it is slightly duplicative.

http://pandas-docs.github.io/pandas-docs-travis/api.html#categorical

also need to add other public methods (that are not available on .cat). This is actually a big list, things like:

isnull, unique, map, value_counts, etc.

These are all Series like methods / accessors.

[jreback]

@TomAugspurger @jorisvandenbossche

[jreback]

I pushed a tiny update: b4c6fc1

but I think should create a separate sub-section for this

[jorisvandenbossche]

I think this absence was rather intentional. Because people should actually mostly use categorical Series, we didn't want to give too much attention to plain Categorical in the docs?

Quoting from the API docs:

The following two Categorical constructors are considered API

which shows the Categorical / Cateogorical.from_codes constructors. This implies that the rest of the methods are not considered as public API.
I actually think a Categorical should not have a value_counts, so IMO should not be added.

[jreback]

the problem is we cannot reference these from other doc-strings then. I suppose we could have a hidden section?

[jreback]

I mainly wanted to reference Categorical.unique (for the examples, even though they are in pd.unique)

[jorisvandenbossche]

I think we should just not reference them then, as you say yourself, the examples are also in pd.unique (but the categorical unique is indeed a case where there is now additional information in that docstring that is useful).

People will actually typically look at Series.unique docstring when they work interactively and have a categorical series. And looking at that now, there are no examples included there, but all are in pd.unique. So maybe we should include them there as well, or explicitly state "see pd.unique docstring for full documentation" ?