DOC: document subclasses in API docs with selection of specific methods/attributes
State: closed

xref https://github.com/pandas-dev/pandas/issues/18147

OK, https://github.com/pandas-dev/pandas/commit/500ab71bda109327cf191a11fcf514eaffd70167 removes our hack in the vendored `numpydoc/numpydoc.py` to exclude autosummary generation for certain methods. Instead, we'll explicitly list the relevant methods in a new `Methods` section in those docs. This let's us include things like `IntervalIndex` in the API docs, without having all the regular index methods in the table, and without auto-gen making pages for all of those.

The downside is that we have to list the methods in `Methods` in the docstring and under a toctree in `api.rst`. But that's not so bad.

https://github.com/pandas-dev/pandas/commit/257fc8a0af7de854d0f5e2f0bbc9380320760c69 is removing all the warnings about references a non-existent document / this document isn't included in a toctree. But it's a bit tedious so I'll come back later (~600 warnings remaining :/ )



Labels:
name: Docs

Comments:
cc @jorisvandenbossche 
> The downside is that we have to list the methods in Methods in the docstring and under a toctree in api.rst. But that's not so bad.

While looking at the autodoc code, I was thinking of a possible different way that would not need this listing in both places. There is a `autodoc-skip-member` event emitted, where we might be able to skip certain members depending on the class (but not sure this would actually work for our use case, or would actually be better)

> 257fc8a is removing all the warnings about references a non-existent document / this document isn't included in a toctree. But it's a bit tedious so I'll come back later (~600 warnings remaining :/ )

Are you sure this is needed? As it is currently not needed to not get the warnings (I see you set `numpydoc_show_class_members` to False, is that related?) And is this independent from the manual Methods listing, or is this a consequence of trying to fix that?
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=h1) Report
> Merging [#18202](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/63e8527d32aaf6afe1cd4b2a7b3bfadb088c9a72?src=pr&el=desc) will **decrease** coverage by `0.04%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/18202/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #18202      +/-   ##
==========================================
- Coverage    91.4%   91.35%   -0.05%     
==========================================
  Files         164      164              
  Lines       49880    49854      -26     
==========================================
- Hits        45591    45545      -46     
- Misses       4289     4309      +20
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.16% <ø> (-0.03%)` | :arrow_down: |
| #single | `39.44% <ø> (-0.04%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.45% <ø> (ø)` | :arrow_up: |
| [pandas/core/tools/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvdG9vbHMvZGF0ZXRpbWVzLnB5) | `84.48% <ø> (ø)` | :arrow_up: |
| [pandas/core/reshape/reshape.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS9yZXNoYXBlLnB5) | `100% <ø> (ø)` | :arrow_up: |
| [pandas/io/formats/style.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvc3R5bGUucHk=) | `100% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `97.46% <ø> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <ø> (-58.34%)` | :arrow_down: |
| [pandas/core/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY2F0ZWdvcmljYWwucHk=) | `95.75% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/period.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9wZXJpb2QucHk=) | `92.9% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `91.14% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `96.38% <ø> (ø)` | :arrow_up: |
| ... and [11 more](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=footer). Last update [63e8527...34834fa](https://codecov.io/gh/pandas-dev/pandas/pull/18202?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Sorry I made a mistake earlier w/ the warnings. Most are coming from me forgetting to use the `class_without_autosummary` template.

I'm not sure why things like `DataFrame.as_blocks` are causing warning now.
Doing a clean build again. Some things I would appreciate feedback on:

1. I was probably inconsistent with where I put these methods (either sections or in the 'hidden' section at the bottom) 
2. Do we want to setup a linter on the sphinx build so that CI fails when there are any warnings?
3. Methods like `.mul` and `.multiply`: do we want to list both?
How do the rendered docstring pages look like of those classes where you included it manually? 
> attributes and then methods

Yes, I've been inconsistent. I'll fix that. There's a numpydoc issue talking about emitting warnings if the sections aren't in the correct order.

> How do the rendered docstring pages look like of those classes where you included it manually?


I think everything looks correct:

![screen shot 2017-11-12 at 10 39 03 am](https://user-images.githubusercontent.com/1312546/32701140-c66a3a1c-c795-11e7-8045-939f078411e9.png)

FYI: the warnings are now down to the cyfunc ones and a whole bunch of new ones from the offsets :) I'm going to think about the offsets ones, they aren't super useful in their current state.
And the docstring pages for those that should have all automatically like DataFrame, they still list them all?
> I'm going to think about the offsets ones, they aren't super useful in their current state.

mea culpa. upside is I have a PR with some doc-strings :>
> FYI: the warnings are now down to the cyfunc ones and a whole bunch of new ones from the offsets :) I'm going to think about the offsets ones, they aren't super useful in their current state.

I would personally be fine with removing them again temporary if that makes us to go faster towards fully working docs (I don't know how much work it is to fix them), to achieve a warning free build, and then once everything is in place we can add them properly.
> I would personally be fine with removing them again temporary if that makes us to go faster towards fully working docs (I don't know how much work it is to fix them), to achieve a warning free build, and then once everything is in place we can add them properly.

ok too. I really just needed to_offset.
> And the docstring pages for those that should have all automatically like DataFrame, they still list them all?

Ah, no! I'm rebuilding with `show_class_members = True`, which I hope will fix that. I don't recall why I set that to False a while back.
> mea culpa. upside is I have a PR with some doc-strings :>

:) No worries. I was a bit surprised when I thought I had all the warnings squashed and it jumped to 200+ again :)
> I'm rebuilding with show_class_members = True, which I hope will fix that. I don't recall why I set that to False a while back.

Hmm apparently that's necessary to make the methods section work? I now see warnings like

```
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Categorical.rst:101: WARNING: toctree references unknown document 'generated/pandas.Categorical.add_categories'
```

and

```
<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'generated/pandas.Grouper.ax'
```

and 

```
None:None: WARNING: toctree contains reference to nonexisting document 'generated/pandas.Categorical.add_categories'
```

2373 warnings in total. Everything seems to render correctly though...
Hello @TomAugspurger! Thanks for updating the PR.



































Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on November 15, 2017 at 15:22 Hours UTC
FYI @jorisvandenbossche, the trick of duplicating the function signature on the first line of the cython functions worked (locally at least).
All green. https://travis-ci.org/pandas-dev/pandas/jobs/301600593#L2381 has 255 warnings. I've built it locally with numpdoc master and those warnings are gone (though we can't switch to numpydoc master until https://github.com/numpy/numpydoc/pull/106#issuecomment-343220139 is resolved.
I still don't fully understand why it is now needed to include all methods/attributes in api.rst to avoid warnings while before this was not needed. What did change related to that?
> The additional warnings come from numpydoc master. Building pandas's master with numpydoc master causes warnings for pages that are auto-generated, but not included in a toctree.

That's strange, because I am testing numpydoc master with sphinx 1.6, and there I don't get such warnings (at least not for the methods, there is a problem with the attributes I am trying to figure out)
> I've hopefully address all the comments (thanks) but going through again to double check.

The `.rst` in entries in api.rst are in any case still there
Ah, perhaps it's an interaction between old sphinx and new numpydoc then. I'll test those out.
The thing is that the 'HACK' in the template (that includes a full autosummary with toctree) currently ensures that every single method/attribute is included. If possible, I still think that is useful. Although, on the other hand, having to explicitly list them in api.rst (even if it is hidden), is in some way more explicit (we explicitly have to choose which ones we show and which ones we hide)
> The .rst in entries in api.rst are in any case still there

Fixed

> currently ensures that every single method/attribute is included. If possible, I still think that is useful. 

AFAIU, that still happens in the PR for any class that uses the `_templates/autosummary/class.rst` template. Or am I missing something?

For classes like `CategoricalIndex` we do not generate pages like `CategoricalIndex.transpose`, since

- The `CategorialIndex` toctree uses `class_without_autosummary`
- `CategoricalIndex` defines `Methods`
> > currently ensures that every single method/attribute is included. If possible, I still think that is useful.

> AFAIU, that still happens in the PR for any class that uses the _templates/autosummary/class.rst template. Or am I missing something?

Yes, I would think so. But that was the main reason of my question: why is it needed to add all methods of Series/DataFrame/Panel to api.rst (hidden or not) since they don't use template without hack

I think they do:

```
DataFrame
---------

Constructor
~~~~~~~~~~~
.. autosummary::
   :toctree: generated/

   DataFrame

```

Or did I change that?
No, you didn't change that, so they are using the default `class.rst` template, which includes the hack (it is `class_without_autosummary.rst` that does not include the hack), and so it should not be necessary to add all methods in api.rst ?
But again, now you already did the work, I am not fully sure it is necessarily needed to revert part of it if it seems it was not needed, if we like the explicitness of it (although it will give a bit more maintenance work for api.rst)
> and so it should not be necessary to add all methods in api.rst ?

I'll double check, but the warnings I was getting was like "this pandas.Series.hasnans.rst file is not included in any toctree" since it was autogenerated, but not included in `api.rst`. I think that's the ideal behavior? We *want* a warning when we've forgotten to include it (potentially in the `:hidden:` toctree).
Hasnans is an attribute. Did you also get the same for warnings for methods? I also had problems with attributes, but think this is a bug / related to the attributes table formatting issue