improve the documentation of sage/misc/cython.py

[jhpalmieri]

Various functions in cython.py have no documentation. The attached patch improves this. Note that after apply the patch, sage --coverage cython.py does not report 100%, because some multiline strings are interpreted as undocumented functions/classes/methods by the coverage script. Also, the function cython has no doctests. Suggests for that?

This also adds cython.py to the reference manual.

Component: misc

Author: John Palmieri, David Loeffler

Reviewer: David Loeffler, John Palmieri

Merged: sage-5.0.beta9

Issue created by migration from https://trac.sagemath.org/ticket/11954

[jhpalmieri]

comment:1

Attachment: trac_11954-cython-doc.patch.gz

[jhpalmieri]

comment:2

(This is a follow-up to #11887. In that ticket, we changed the documentation from the cython function from being completely empty to being "TODO: document this function!")

[nexttime]

Replying to @jhpalmieri:

sage --coverage cython.py does not report 100%, because some multiline strings are interpreted as undocumented functions/classes/methods by the coverage script.

Did you open a ticket for that? ;P

[jhpalmieri]

comment:4

It might actually be covered by #7716, but I haven't tested it.

[jdemeyer]

Milestone sage-4.7.3 deleted

[loefflerd]

comment:6

Apply trac_11954-cython-doc.patch, trac_11954-review.patch

Here's a new patch which makes various cosmetic changes to the Sphinx formatting. I wasn't sure what the mysterious "sagobject_name" was supposed to mean in the docstring of the cython lambda function and the doctests weren't too helpful on that point; I'm guessing it's a typo for sage.object_name.

If you're happy with my reviewer patch, that's a positive review.

[loefflerd]

Reviewer: David Loeffler

[jhpalmieri]

comment:7

I'm mostly happy with the reviewer patch -- thanks for your work on this, it looks much better now. However, I don't like line 314:

'``Compiling <filename>...``'

The quotes don't look good after running Sphinx. Maybe it should be ``'Compiling ...'``? Or maybe the single quotes should be dropped? Or drop the double back quotes instead?

[loefflerd]

Attachment: trac_11954-review.patch.gz

Apply over previous patch

[loefflerd]

comment:8

Apply trac_11954-cython-doc.patch, trac_11954-review.patch

This patch goes for the ``'foo'`` option.

[jhpalmieri]

Changed reviewer from David Loeffler to David Loeffler, John Palmieri

[jhpalmieri]

comment:9

Great, looks good to me.

[jhpalmieri]

Changed author from John Palmieri to John Palmieri, David Loeffler

[jdemeyer]

Merged: sage-5.0.beta9