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)

trac_7683.patch (800 bytes) - added by mhansen 11 years ago.
sphinx-0.6.3.p3.patch (5.4 KB) - added by mhansen 11 years ago.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 11 years ago by was

  • 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 jhpalmieri

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.

comment:3 Changed 11 years ago by mhansen

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 mhansen

Changed 11 years ago by mhansen

comment:4 Changed 11 years ago by mhansen

  • Authors set to Mike Hansen
  • 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: Changed 11 years ago by jhpalmieri

  • 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 jhpalmieri

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 mhansen

  • 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 was

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 mhansen

  • Merged in set to sage-4.3.rc1
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.