DOC: document subclasses in API docs with selection of specific methods/attributes #18202
Conversation
doc/source/api.rst
Outdated
| @@ -845,12 +863,16 @@ Binary operator functions | |||
|
|
|||
| DataFrame.add | |||
| DataFrame.sub | |||
| DataFrame.subtract | |||
There was a problem hiding this comment.
Thoughts on these aliases? IMO, since there methods we should document them. But I can also put them in our "hidden" block down below.
There was a problem hiding this comment.
We should document them in the sense that they have a docstring and will end up in the class docstring page of DataFrame in the full list of members, but I don't think that should mean we should include them all in this place.
doc/source/api.rst
Outdated
| @@ -692,6 +698,10 @@ adding ordering information or special categories is need at creation time of th | |||
| .. autosummary:: | |||
| :toctree: generated/ | |||
|
|
|||
| Categorical.categories | |||
There was a problem hiding this comment.
I know that this is the wrong place for this (doesn't fit w/ the text above). I'm going to make a dedicated section for Categorical.
| ---------- | ||
| codes | ||
| categories | ||
| ordered |
There was a problem hiding this comment.
Ideally we would add here a sentence with something like "For all other methods, see Index", but I am not sure that is allowed in Attributes / Methods sections?
There was a problem hiding this comment.
I suspect not. I've been thinking of ways to handle this.
I'm not worried about people reading the source / in IPython. They already have the code or object.
I think in the Notes section we can say "See :class:Index for additional methods." or something like that.
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
Are you sure this is needed? As it is currently not needed to not get the warnings (I see you set |
Codecov Report
@@ 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
Continue to review full report at Codecov.
|
|
Sorry I made a mistake earlier w/ the warnings. Most are coming from me forgetting to use the I'm not sure why things like |
|
Doing a clean build again. Some things I would appreciate feedback on:
|
doc/source/api.rst
Outdated
| Series.imag | ||
| Series.real | ||
| Series.name | ||
| Series.put |
There was a problem hiding this comment.
I have the feeling that we don't want to include all of those here (eg imag, real). If that is needed for getting rid of warnings, we can put them in comment?)
There was a problem hiding this comment.
I didn't look closely in this last round. Happy to move them to the bottom hidden section.
There was a problem hiding this comment.
And yes, it's for warnings. Every method of a class that uses the default class template (with autosummary) will need to be listed in a toctree. That's why I've added the :hidden: toctree at the bottom. I'll also update contributing.rst with some details.
doc/source/api.rst
Outdated
| @@ -845,12 +863,16 @@ Binary operator functions | |||
|
|
|||
| DataFrame.add | |||
| DataFrame.sub | |||
| DataFrame.subtract | |||
There was a problem hiding this comment.
We should document them in the sense that they have a docstring and will end up in the class docstring page of DataFrame in the full list of members, but I don't think that should mean we should include them all in this place.
doc/source/conf.py
Outdated
| @@ -67,6 +67,7 @@ | |||
| ] | |||
|
|
|||
| exclude_patterns = ['**.ipynb_checkpoints'] | |||
| numpydoc_show_class_members = False | |||
There was a problem hiding this comment.
Do you know why this is needed?
|
How do the rendered docstring pages look like of those classes where you included it manually? |
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.
I think everything looks correct:
|
|
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? |
mea culpa. upside is I have a PR with some doc-strings :> |
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. |
Ah, no! I'm rebuilding with |
:) No worries. I was a bit surprised when I thought I had all the warnings squashed and it jumped to 200+ again :) |
Hmm apparently that's necessary to make the methods section work? I now see warnings like and and 2373 warnings in total. Everything seems to render correctly though... |
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 |
|
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 |
@jorisvandenbossche just tested again and you're correct. It is just unlisted attributes that emit a warning on numpydoc master. Methods do not. |
|
OK, that mystery is solved then :-) So the question now is: given you did the work, do we just keep them in there? (all the hidden ones) |
|
Those last two commits should do it, although I get a bizarre warning for Float64Index: But not any of the other numeric indexes. |
|
Merging later today if there are no other comments. |
|
I just did a local build with this branch, it is looking fine! (using numpydoc master as well, but with sphinx 1.5) I just got a big bunch of warnings on Timestamp.fold not being importable / toctree referencing nonexisting document, because this is new in py3.6 (my dev env is still 3.5). So that will be the case for everybody building on py < 3.6. Further question, just for my understanding: do you know why numpydoc, for the class docstring pages where we manually listed the attributes/methods, it did not add the rest in that list as well (as it seems this is what is happening in eg scipy (https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.Delaunay.html#scipy.spatial.Delaunay was given as example in the numpydoc issue. There the manually specified and automatically generated autosummary table seems to be fused / numpy/numpydoc#106 (comment)) |
jorisvandenbossche
changed the title
|
@TomAugspurger Thanks a lot for this! |
|
@TomAugspurger Do we try to include this for 0.21.1, or leave for 0.22? (I am not sure how cleanly it will backport, and then also the related PRs should be backported) |
|
it would be nice to backport but might be some work |
Was dropped in pandas-devgh-15099 but accidentally added back in pandas-devgh-18202. Follow-up to pandas-devgh-23375.
Was dropped in pandas-devgh-15099 but accidentally added back in pandas-devgh-18202. Follow-up to pandas-devgh-23375.
Was dropped in pandas-devgh-15099 but accidentally added back in pandas-devgh-18202. Follow-up to pandas-devgh-23375.
Was dropped in pandas-devgh-15099 but accidentally added back in pandas-devgh-18202. Follow-up to pandas-devgh-23375.
xref #18147
OK, 500ab71 removes our hack in the vendored
numpydoc/numpydoc.pyto exclude autosummary generation for certain methods. Instead, we'll explicitly list the relevant methods in a newMethodssection in those docs. This let's us include things likeIntervalIndexin 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
Methodsin the docstring and under a toctree inapi.rst. But that's not so bad.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 :/ )