Closed JohnCremona closed 14 years ago
Applies to 4.3.1.rc0
Attachment: trac_7948-docstrings.patch.gz
Attachment: trac_7948-docstrings.2.patch.gz
Applies to 4.3.1.rc0
The patch fixes quite a few of these, but there are several categories of error whcich I do not understand at all, for example these:
/home/john/sage-4.3.1.rc0/devel/sage/doc/en/reference/sage/categories/category.rst:6: (WARNING/2) error while formatting signature for sage.categories.category.Category.element_class: obj is not a code object
/home/john/sage-4.3.1.rc0/devel/sage/doc/en/reference/sage/graphs/base/c_graph.rst:6: (WARNING/2) error while formatting signature for sage.graphs.base.c_graph.CGraphBackend.depth_first_search: arg is not a Python function
/home/john/sage-4.3.1.rc0/devel/sage/doc/en/reference/sage/matrix/matrix2.rst:6: (WARNING/2) error while formatting signature for sage.matrix.matrix2.Matrix.integer_kernel: Could not parse cython argspec
Still, if the attached patch applies ok and the docs rebuild ok then it would be worth merging, even though there are outstanding errors.
I think that "obj is not a code object" arises for methods marked as "lazy_attributes". These probably need to be dealt with in some special way, but I don't know how to do it. Maybe it deserves its own ticket.
"Could not parse cython argspec" happens for several reasons. In lots of cases, it's for functions with no arguments in cython files: def f():
. There is a mistake in sageinspect.py which causes such functions to raise this error. I'm working on a patch. Actually, the code in sageinspect.py for producing docstrings for cython functions, and in particular for returning the list of arguments and their default values, has some problems and ought to be rewritten. Again, maybe this belongs on another ticket.
"arg is not a Python function": I don't know where this comes from.
Two out of three is good going! I'm in favour of branching this into separate tickets as specific problems are identified.
My patch could still do with a review! (There's only one; for some reason it got attached twice, but I don't know how to delete the duplicate).
I'll give John Cremona's patch a positive review, and I'm attaching another one which should be applied either before or after his. I'm running doctests to make sure it doesn't break anything. Here's a summary of what happens when I build the reference manual:
no patches: 237 warnings
cremona's patch: 220 warnings
jhpalmieri's patch: 179 warnings
both patches: 162 warnings
Attachment: trac_7948-cythonargspec.patch.gz
Here's a third patch; together with the others, this gets us down to 144 warnings. One of the remaining warnings is because of the problems I mentioned earlier about the sageinspect.py code for cython functions -- the code essentially needs to parse the def f(...):
part of the function to find the arguments. Right now, it does some simple searching to find the part (...)
in parentheses, and then it splits that up at each comma. This breaks if there is a default argument like (vec=(1,0,0))
, and leads to the message "Could not parse cython argspec".
For most of the other 143 warnings, I don't know what to do. (There are some easy ones, but they're in sagenb, and I don't feel like working on that right now. It should probably be a separate ticket, anyway.)
Sometimes, I also get the message
checking consistency... /Applications/sage/devel/sage/doc/en/reference/sage/misc/attach.rst:: WARNING: document isn't included in any toctree
To deal with this, delete (by hand) the file SAGE_DOC/en/reference/sage/misc/attach.rst
.
apply on top of the other two patches
Attachment: trac_7948-lazy.patch.gz
I'm about to test John P's two patches on top of mine. If all goes well I'll give the ticket a positive review (since John already positively reviewed my patch), and then we can make a new patch for what remains.
Attachment: trac_7948-part4.patch.gz
Apply after previous
Positive review to John P's two patches. In testing, I spotted one more "easy" one, whic hI had to fix since I had written that docstring (I think). Hence the small "part 4" patch.
Author: John Cremona, John Palmieri
Reviewer: John Palmieri, John Cremona
Merged: sage-4.3.1.rc1
Merged (in this order):
trac_7948-docstrings.2.patch
trac_7948-cythonargspec.patch
trac_7948-lazy.patch
trac_7948-part4.patch
Building the docs for 4.3.1.rc0 produces these errors:
These should all be fixed before the release.
CC: @jhpalmieri
Component: documentation
Author: John Cremona, John Palmieri
Reviewer: John Palmieri, John Cremona
Merged: sage-4.3.1.rc1
Issue created by migration from https://trac.sagemath.org/ticket/7948