Opened 9 years ago
Closed 7 years ago
#13907 closed defect (fixed)
Fix docstrings in sage/ext/fast_eval.pyx
Reported by:  ppurka  Owned by:  mvngu 

Priority:  major  Milestone:  sage6.5 
Component:  documentation  Keywords:  beginner, days57 
Cc:  Merged in:  
Authors:  Charles Fougeron  Reviewers:  Vincent Delecroix, Frédéric Chapoton, Marc Mezzarobba 
Report Upstream:  N/A  Work issues:  
Branch:  05f65e7 (Commits, GitHub, GitLab)  Commit:  05f65e7ee725d261969ca8e447ef2cef5e3a995c 
Dependencies:  Stopgaps: 
Description
The docstrings in this file are quite messed up. Changes are needed throughout the file, since the output documentation is never formatted correctly.
Change History (23)
comment:1 Changed 9 years ago by
 Keywords beginner added
comment:2 Changed 9 years ago by
comment:3 Changed 9 years ago by
 Status changed from new to needs_info
Well, I am afraid, at the moment, this file is not a part of the documentation that we build. Do you intend this ticket to serve for the addition of this file into our documentation or am I missing something?
~KnS
comment:4 Changed 9 years ago by
I know that it doesn't add to the documentation. But, documentation is not the only place where a wellformatted docstring is needed. I stumbled across this when checking some function's help in the notebook. It's a mess. Because it is not present in the main documentation, it has been a low priority job for me too. If you have already fixed the docs, then put it up here and I will review it.
comment:5 followup: ↓ 6 Changed 9 years ago by
Hello!
I am having difficulty how I'd go around verifying if I am doing it right. I build after modifying and check the docs from the notebook  it is the same, although I expect some improvement! Should I commit? Please leave some pointers so I could work on this, when I get time.
comment:6 in reply to: ↑ 5 Changed 9 years ago by
Replying to knsam:
Hello!
I am having difficulty how I'd go around verifying if I am doing it right. I build after modifying and check the docs from the notebook  it is the same, although I expect some improvement! Should I commit? Please leave some pointers so I could work on this, when I get time.
Hello, you need to do the following.
 Start a notebook and open a new worksheet.
 Do your modifications to the file. Save it and rebuild it using
sage b
 Go to the worksheet and select
Action > Restart worksheet
.  Go to step 2 until done.
:)
To test your modifications:
 For the stuff at the top of the file, simply evaluate
sage.ext.fast_eval?
(or press TAB after typing that path). If there are stuff like "Traceback...." in the doctest, then evaluating it might not show the full documentation. This is a bug in the notebook. In this case, either simply press TAB, or click to the left of the cell output just once, and you will see the full doctest.  For classes within that file, again simply evaluate them or press TAB, for instance you would see the output of the docstring in the class
FastDoubleFunc
by runningsage.ext.fast_eval.FastDoubleFunc?
.  For the methods within a class, use the full path to the method again, for example
sage.ext.fast_eval.FastDoubleFunc.__cmp__?
.  Finally, for functions within the file, again give the full path
sage.ext.fast_eval.fast_float?
.  If you have written each of those functions, methods, etc, in a different cell, then after selecting "Action > Restart worksheet" after a rebuild of sage, you can select "Action > Evaluate all" to evaluate all the cells. It is fast way to check your modifications.
The functions or methods which are starting with cdef
are never visible from the python interface, so it is up to you whether you want to fix the docstrings in them or not. For a first pass, just leave them alone since there is no way to verify whether they are fixed or not.
EDIT: You do not need to build the docs with sage docbuild
, make doc
, etc. You just need to build sage using sage b
.
comment:7 Changed 8 years ago by
 Milestone changed from sage5.11 to sage5.12
comment:8 Changed 8 years ago by
 Milestone changed from sage6.1 to sage6.2
comment:9 Changed 7 years ago by
 Branch set to u/Fougeroc/Fix_docstrings_in_fast_eval.pyx
 Commit set to 4852acdb0032c5625efd8de1aa7ad701196f4f92
 Status changed from needs_info to needs_review
New commits:
4852acd  Some fixings on the documentation.

comment:10 Changed 7 years ago by
 Keywords days57 added
 Status changed from needs_review to needs_work
For string formatting, you should look at the developer's guide http://www.sagemath.org/doc/developer/coding_basics.html#docstringmarkupwithrestandsphinx
Comments:
 remove trailing whitespaces (line 27, 42, ...)
 the docstring at the begining of the file should not be indented
 NOTE, AUTHOR field is not appropriately formated
 in
_richcmp_
(line 928), you should add a linebreak between the description "Compare left and right." and the beginig of the examples
More to come at your next commit...
comment:11 Changed 7 years ago by
 Commit changed from 4852acdb0032c5625efd8de1aa7ad701196f4f92 to b69868544cf3035ce0a17aa855d533572cf609c8
Branch pushed to git repo; I updated commit sha1. New commits:
b698685  Some further changes in documentation.

comment:12 Changed 7 years ago by
 Status changed from needs_work to needs_review
comment:13 Changed 7 years ago by
 Status changed from needs_review to needs_info
I now get an error when creating the doc
sage docbuild reference/libs html OSError: [libs ] /src/sage6.1.1/src/doc/en/reference/libs/sage/ext/fast_eval.rst:11: WARNING: error while formatting signature for sage.ext.fast_eval.FastDoubleFunc.abs: The given source does not contain 'def'
I don't know how to solve it.
comment:14 Changed 7 years ago by
 Milestone changed from sage6.2 to sage6.3
comment:15 Changed 7 years ago by
 Milestone changed from sage6.3 to sage6.4
comment:16 Changed 7 years ago by
 Branch changed from u/Fougeroc/Fix_docstrings_in_fast_eval.pyx to public/ticket/13907
 Commit changed from b69868544cf3035ce0a17aa855d533572cf609c8 to a7b443b7f2516d5883cb3b444a577f7713eaabaf
comment:17 Changed 7 years ago by
 Commit changed from a7b443b7f2516d5883cb3b444a577f7713eaabaf to 05f65e7ee725d261969ca8e447ef2cef5e3a995c
comment:18 Changed 7 years ago by
 Status changed from needs_info to needs_review
This seems to be ok. I do not see the above problem with
sage docbuild reference/libs html
comment:19 Changed 7 years ago by
author name please...
comment:20 Changed 7 years ago by
comment:21 Changed 7 years ago by
 Reviewers set to Vincent Delecroix, Frédéric Chapoton, Marc Mezzarobba
 Status changed from needs_review to positive_review
The period at the end of the title should be removed for consistency, but I can take care of that in another ticket I'm working on, no need to further delay this one.
comment:22 Changed 7 years ago by
 Milestone changed from sage6.4 to sage6.5
comment:23 Changed 7 years ago by
 Branch changed from public/ticket/13907 to 05f65e7ee725d261969ca8e447ef2cef5e3a995c
 Resolution set to fixed
 Status changed from positive_review to closed
Just so that we don't duplicate work, I am working on this one. :)