Ticket #6664 (closed defect: fixed)
[with patch, positive review] Update autodoc-skip-member for Sphinx v0.6.x
| Reported by: | mpatel | Owned by: | tba |
|---|---|---|---|
| Priority: | minor | Milestone: | sage-4.1.2 |
| Component: | documentation | Keywords: | |
| Cc: | Work issues: | ||
| Report Upstream: | Reviewers: | John Palmieri | |
| Authors: | Mitesh Patel | Merged in: | Sage 4.1.2.alpha0 |
| Dependencies: | Stopgaps: |
Description (last modified by mpatel) (diff)
This just tweaks #6419 so that it works with Sphinx v0.6.x's autodoc extension. The main change is to defer to Sphinx's decision, if the object is not a nested class.
See this comment at #6586 for more.
Attachments
-
trac_6664-skip_nested.patch
(1.2 KB) -
added by mpatel 4 years ago.
- "Depends" on #6586.
Change History
Changed 4 years ago by mpatel
-
attachment
trac_6664-skip_nested.patch
added
comment:1 Changed 4 years ago by mpatel
- Description modified (diff)
- Summary changed from [with patch, needs review] Skip nested classes in docs by Sphinx v0.6.x to [with patch, needs review] Update autodoc-skip-member for Sphinx v0.6.x
comment:2 Changed 4 years ago by jhpalmieri
This suppresses the private methods (__init__, etc.). I'm not sure this is a good idea. Before the transition to Sphinx, these were included in the reference manual, and then they weren't post-Sphinx, I think mainly because the default was to not include them. I think they should be included.
comment:3 Changed 4 years ago by mpatel
- Summary changed from [with patch, needs review] Update autodoc-skip-member for Sphinx v0.6.x to [with patch, needs work] Update autodoc-skip-member for Sphinx v0.6.x
Sounds good. I should have understood and remembered. How about a docbuild option to select between "developer" and "user" documentation? Or is this not a meaningful distinction? Are there any private methods we should always suppress? Of course, we can just close this ticket (or mark it as invalid).
comment:4 follow-up: ↓ 5 Changed 4 years ago by jhpalmieri
- Reviewers set to John Palmieri
- Milestone set to sage-4.1.2
- Summary changed from [with patch, needs work] Update autodoc-skip-member for Sphinx v0.6.x to [with patch, positive review] Update autodoc-skip-member for Sphinx v0.6.x
- Authors set to Mitesh Patel
I think that having different versions of the reference manual was discussed at some point, but without definite outcomes or guidelines. Maybe it should be discussed on sage-devel?
At the moment, though, including private methods is a bit problematic. First, __weakref__ appears sort of at random, and then some classes get all sorts of weird extra methods, maybe inherited from another class? See the Matrix class in SAGE_ROOT/devel/sage/doc/output/html/en/reference/sage/matrix/matrix0.html, for example; there is an entry for __delitem__, and the entry for __init__ is wrong: it looks generic rather than the one which is actually in the file. Maybe this has to do with it being Cython rather than Python.
Is it better to exclude all private methods, or to include them at the price of having all sorts of extra crap in addition? I say we continue to exclude them until we can figure out how to fix this. So let's keep this patch for now. I'll give it a positive review.
Does this really depend on #6586, or can it be merged now?
comment:5 in reply to: ↑ 4 Changed 4 years ago by mpatel
Replying to jhpalmieri:
Does this really depend on #6586, or can it be merged now?
It's not dependent, according to du -s. I tested this with and without the patch, with Sphinx 0.5.1.
"Depends" on #6586.