Opened 11 years ago
Closed 11 years ago
#7683 closed defect (fixed)
sphinx reference manual documentation has a major issue: in some cases the input parameters to functions are completely omitted causing great confusion!
| Reported by: | was | Owned by: | mvngu |
|---|---|---|---|
| Priority: | critical | Milestone: | sage-4.3 |
| Component: | documentation | Keywords: | |
| Cc: | Merged in: | sage-4.3.rc1 | |
| Authors: | Mike Hansen | Reviewers: | John Palmieri |
| Report Upstream: | N/A | Work issues: | |
| Branch: | Commit: | ||
| Dependencies: | Stopgaps: |
Status badges
Description
See
http://sagemath.org/doc/reference/sage/rings/integer.html#sage.rings.integer.Integer.jacobi
Notice that the input parameter b is simply totally omitted from the function signature. In sharp contrast, if you type
sage: a = 5 sage: a.jacobi(<tab>
in the notebook, then you'll see the correct sphinx-rendered documentation *with* the other input argument. This is very bad and confusing for some users who trust reference manuals, especially because evidently the use of INPUT/OUTPUT blocks to describe parameters of functions is not being used nearly as much as it should be (there will be another ticket about that).
Attachments (2)
Change History (11)
comment:1 Changed 11 years ago by
- Summary changed from sphinx reference manual documentation has a *major* issues: in some cases the input parameters to functions are completely omitted causing great confusion! to sphinx reference manual documentation has a major issue: in some cases the input parameters to functions are completely omitted causing great confusion!
comment:2 Changed 11 years ago by
comment:3 Changed 11 years ago by
The problem is that Sphinx needs to use the functions in sage.misc.sageinspect to get the function signature as inspect.getargspec doesn't work with Cython modules.
Changed 11 years ago by
Changed 11 years ago by
comment:4 Changed 11 years ago by
- Status changed from new to needs_review
I've attached a patch for the Sage library which uses the new spkg at http://sage.math.washington.edu/home/mhansen/sphinx-0.6.3.p3.spkg . The changes in this spkg are at sphinx-0.6.3.p3.patch .
comment:5 follow-up: ↓ 6 Changed 11 years ago by
- Reviewers set to John Palmieri
- Status changed from needs_review to positive_review
It looks good to me, and I understand the general principle behind the patch, but not necessarily the details. (For instance, and this has more to do with Sphinx than the patch, why is essentially the same code repeated four times?)
The output seems to fix the complaint, too. Is this worth reporting to the Sphinx people as a suggested addition to their code?
comment:6 in reply to: ↑ 5 Changed 11 years ago by
Replying to jhpalmieri:
It looks good to me, and I understand the general principle behind the patch, but not necessarily the details. (For instance, and this has more to do with Sphinx than the patch, why is essentially the same code repeated four times?)
(Well, twice, not four times, but still.)
comment:7 Changed 11 years ago by
- Milestone changed from sage-4.3.1 to sage-4.3
One place is for methods and the other is for functions.
I sent Georg a message about it, but I haven't heard back from him. I'll try to push this upstream
comment:8 Changed 11 years ago by
I also give this a positive review. I tested the code and also read it, and it makes sense to me and works.
comment:9 Changed 11 years ago by
- Merged in set to sage-4.3.rc1
- Resolution set to fixed
- Status changed from positive_review to closed
Is this only with .pyx files, or are there problems with .py files, too? A random search through a few files suggests that it's only .pyx files (and perhaps all .pyx files) which cause problems. I don't know what this means, but maybe someone can figure it out.