Doc Day 1 announcement: January 17th, 2008, 9am-5pm PST

2 views
Skip to first unread message

mabshoff

unread,
Jan 16, 2008, 11:52:07 AM1/16/08
to sage-support, sage-...@googlegroups.com
Hello folks,

after doing 8 Bug Days the time has come to spend some more time on
the documentation, which also needs a lot of work. So after some
discussion in IRC we decided to get together in IRC at the above date
and time and work on the documentation. Since we have never done a doc
day it isn't 100% clear to me how the whole thing will go down, but I
assume we will just go with the flow.

Thoughts? Suggestions?

Cheers,

Michael

Martin Albrecht

unread,
Jan 16, 2008, 12:00:26 PM1/16/08
to sage-...@googlegroups.com

Suggestion: each participant goes through a file of his/her own choice and
makes sure it has 100% doctest coverage. Reading the source of the possibly
unfamiliar file is also encouraged.

Martin


--
name: Martin Albrecht
_pgp: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x8EF0DC99
_www: http://www.informatik.uni-bremen.de/~malb
_jab: martinr...@jabber.ccc.de

David Roe

unread,
Jan 16, 2008, 2:09:34 PM1/16/08
to sage-...@googlegroups.com
Note that I just put up a ticket with patch (1795) that fixes sage-coverage so that it checks cdef'd and cpdef'd functions and classes.
David

Robert Bradshaw

unread,
Jan 16, 2008, 2:17:57 PM1/16/08
to sage-...@googlegroups.com
Sounds like a good idea--I'll be able to participate in the morning
at least. Do we want to require all cdef functions to have doctests?
Also, how to test them?

- Robert

Nick Alexander

unread,
Jan 16, 2008, 2:24:14 PM1/16/08
to sage-...@googlegroups.com

On 16-Jan-08, at 11:17 AM, Robert Bradshaw wrote:

>
> Sounds like a good idea--I'll be able to participate in the morning
> at least. Do we want to require all cdef functions to have doctests?
> Also, how to test them?

I vote to require. Presumably all cdef functions are exercised by
some part of the python accessible code (otherwise, why are they
present?). Doctests in cdef docstrings are found by the doctesting
architecture and executed. So they will be tested, just not in the
most straightforward way :)

Nick

David Roe

unread,
Jan 16, 2008, 2:32:39 PM1/16/08
to sage-...@googlegroups.com
My modification to sage-coverage checks to see that doctests are present in the docstring of a cdef'd function but doesn't check that the function name is there (because it usually won't be).
David

mabshoff

unread,
Jan 16, 2008, 2:35:05 PM1/16/08
to sage-devel


On Jan 16, 8:32 pm, "David Roe" <roed...@gmail.com> wrote:
> My modification to sage-coverage checks to see that doctests are present in
> the docstring of a cdef'd function but doesn't check that the function name
> is there (because it usually won't be).
> David

Nice. Robert, can you review that ticket, too? I would like to merge
it for alpha4 which should be the basis for the Doc Day IMHO.

On a side note: I was under the impression that we would also work on
documentation, while everybody else is talking about doctests ;).

Cheers,

Michael

Robert Bradshaw

unread,
Jan 16, 2008, 2:39:50 PM1/16/08
to sage-...@googlegroups.com

Of course, it'd be nice if every function had ample documentation,
but I'd rather have 100% coverage on all user-accessible functions in
two files, than 100% coverage in one file for def/cpdef and cdef
functions. Also, often the "inderect" tests for cdef functions seem
to be redundant with the doctests exposed functions.

- Robert

David Roe

unread,
Jan 16, 2008, 2:51:33 PM1/16/08
to sage-...@googlegroups.com
Of course, it'd be nice if every function had ample documentation,
but I'd rather have 100% coverage on all user-accessible functions in
two files, than 100% coverage in one file for def/cpdef and cdef
functions. Also, often the "inderect" tests for cdef functions seem
to be redundant with the doctests exposed functions.

The indirect doctests are sometimes reduntant.  But sometimes they are things like _add_c_impl, which won't necessarily get doctested elsewhere.
David

mabshoff

unread,
Jan 16, 2008, 2:56:36 PM1/16/08
to sage-devel
I think it can't hurt to test those. When I need to debug some odd
crash on an experimental platforms with very abstract, high level code
it would greatly help to narrow down the issue if those functions
would also be doctested and exposed when I run -testall on the build.
While it certainly is a lot of effort it would still be worth it. The
only negative impact I would see is that our percentage of -
coverageall would probably do drop quite a bit.

Cheers,

Michael

David Roe

unread,
Jan 16, 2008, 3:01:57 PM1/16/08
to sage-...@googlegroups.com
With the modifications, our overall coverage is at 33.1%.
David

Robert Bradshaw

unread,
Jan 16, 2008, 3:31:25 PM1/16/08
to sage-...@googlegroups.com

I'm not advocating that no cdef functions should have doctests,
certainly things like _add_c_impl should.

- Robert

Reply all
Reply to author
Forward
0 new messages