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: sage-6.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:

Status badges

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 knsam

  • Keywords beginner added

comment:2 Changed 9 years ago by knsam

Just so that we don't duplicate work, I am working on this one. :)

comment:3 Changed 9 years ago by knsam

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

I know that it doesn't add to the documentation. But, documentation is not the only place where a well-formatted 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 follow-up: Changed 9 years ago by 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.

comment:6 in reply to: ↑ 5 Changed 9 years ago by ppurka

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.

  1. Start a notebook and open a new worksheet.
  2. Do your modifications to the file. Save it and rebuild it using sage -b
  3. Go to the worksheet and select Action -> Restart worksheet.
  4. Go to step 2 until done. :-)

To test your modifications:

  1. 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.
  2. 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 running sage.ext.fast_eval.FastDoubleFunc?.
  3. For the methods within a class, use the full path to the method again, for example sage.ext.fast_eval.FastDoubleFunc.__cmp__?.
  4. Finally, for functions within the file, again give the full path sage.ext.fast_eval.fast_float?.
  5. 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.

Last edited 9 years ago by ppurka (previous) (diff)

comment:7 Changed 8 years ago by jdemeyer

  • Milestone changed from sage-5.11 to sage-5.12

comment:8 Changed 8 years ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:9 Changed 7 years ago by Fougeroc

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

4852acdSome fixings on the documentation.

comment:10 Changed 7 years ago by vdelecroix

  • 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#docstring-markup-with-rest-and-sphinx

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 git

  • Commit changed from 4852acdb0032c5625efd8de1aa7ad701196f4f92 to b69868544cf3035ce0a17aa855d533572cf609c8

Branch pushed to git repo; I updated commit sha1. New commits:

b698685Some further changes in documentation.

comment:12 Changed 7 years ago by Fougeroc

  • Status changed from needs_work to needs_review

comment:13 Changed 7 years ago by Fougeroc

  • 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/sage-6.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 vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3

comment:15 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4

comment:16 Changed 7 years ago by chapoton

  • Branch changed from u/Fougeroc/Fix_docstrings_in_fast_eval.pyx to public/ticket/13907
  • Commit changed from b69868544cf3035ce0a17aa855d533572cf609c8 to a7b443b7f2516d5883cb3b444a577f7713eaabaf

I made a few more changes, including correct python3 formatting of raise statements.


New commits:

d4a4efaMerge branch 'u/Fougeroc/Fix_docstrings_in_fast_eval.pyx' of ssh://trac.sagemath.org:22/sage into 6.5.b4
a7b443btrac #13907 further little changes

comment:17 Changed 7 years ago by git

  • Commit changed from a7b443b7f2516d5883cb3b444a577f7713eaabaf to 05f65e7ee725d261969ca8e447ef2cef5e3a995c

Branch pushed to git repo; I updated commit sha1. New commits:

6a24a61Merge branch 'public/ticket/13907' into 6.5.b5
05f65e7trac #13907 minor point, alignement

comment:18 Changed 7 years ago by chapoton

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

author name please...

comment:20 Changed 7 years ago by chapoton

  • Authors set to Charles Fougeron

comment:21 Changed 7 years ago by mmezzarobba

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

  • Milestone changed from sage-6.4 to sage-6.5

comment:23 Changed 7 years ago by vbraun

  • Branch changed from public/ticket/13907 to 05f65e7ee725d261969ca8e447ef2cef5e3a995c
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.