how to write doctests, new policy

[Ondrej Certik]

Hi,

after my branch is reviewed and merged:

http://github.com/certik/sympy/commits/docday/

here is how to improve our docstrings:

1) run coverage_doctest script:

$ bin/coverage_doctest.py sympy/core/basic.py
----------------------------------------------------------------------
sympy/core/basic.py

Missing documentation:
* is_hypergeometric(self, k)
* is_polynomial(self, *syms)
* search(expr)
* search(expr)
* conjugate(self)
* removeO(self)
* getO(e)
* as_powers_dict(self)
* as_base_exp(self)
* as_coeff_terms(self, x=None)
* as_coeff_factors(self, x=None)
* as_numer_denom(self)
* normal(self)
* diff(self, *symbols, **assumptions)
* fdiff(self, *indices)
* integrate(self, *args, **kwargs)
* pattern_match(pattern, expr, repl_dict)
* as_numer_denom(self)
* count_ops(self, symbolic=True)
* doit(self, **hints)
* is_number(self)
* cls_new(cls)
* cls_getnewargs(self)

Missing doctests:
* solve4linearsymbol(eqn, rhs, symbols = None)
* expand(self, deep=True, power_base=True, power_exp=True, mul=True,
\ log=True, multinomial=True, basic=True, **hints)
* series(self, x, point=0, n=6, dir="+")
* lseries(self, x, x0)
* nseries(self, x, x0, n)
* limit(self, x, xlim, direction='+')
* as_coeff_exponent(self, x)

SCORE sympy/core/basic.py: 50% (30 of 60)
----------------------------------------------------------------------

you can pass it any file, or a directory. Then add example doctests to
every function that is reported. Do it by:

$ bin/isympy -c python -p no
[...]
Documentation can be found at http://sympy.org/

>>> x = Symbol("x", positive=True)
>>> x.assumptions0
{'commutative': True, 'complex': True, 'imaginary': False, 'negative':
False, 'nonnegative': True, 'nonpositive': False, 'nonzero': True,
'positive': True, 'real': True, 'zero': False}
>>>

This is important, because doctests use sstrrepr printer, which orders
dictionaries in a hash *independent* way, and so does "bin/isympy -c
python -p no", so you can just copy & paste the output from there to
the docstring. Then check the docstring with:

$ bin/doctest sympy/core/basic.py
============================= test process starts ==============================
executable: /usr/bin/python (2.6.2-final-0)

sympy/core/basic.py[30] .............................. [OK]

================== tests finished: 30 passed in 0.14 seconds ===================

and that's it.

As you can see, the above file has examples in only 50% of all
methods, and that's after my patch here (it used to be only 36%):

http://github.com/certik/sympy/commit/9581a676b1dbc6879b973ea3b49611aa0752aee0

After your feedback to the coverage script and some discussion, I plan
to impose a rule on all new code, that all new methods/functions must
pass the coverage test, e.g. there must be at least one example
doctest. Just like Sage has, but the difference here is that we don't
use doctests for testing the code --- use regular tests in the test/
directories and bin/test for that. However, the example doctests are
there to help the user understand what the function is doing. So those
should be written in a nice pedagogic way.

In the first stage, the coverage script is not checking functions
beginning with "_", since those are meant as private functions, so
those are not so critical for users to understand what they do --- for
now. Once we greate increase example coverage of the whole sympy, we
will uncomment two lines in the coverage script and doctest
everything. This greatly helps people who want to contribute to sympy,
to get oriented and understand what each method is doing.

Unrelated thing: there is a "bin/coverage_report.py" which prints a
coverage report for sympy code (e.g. as sympy tests are covering it,
line by line) and works reasonably well. There are still parts of
sympy, that are not tested enough (e.g. only part of some longer
method is tested). So we should also improve this.

Ondrej

[Ondrej Certik]

On Wed, Jul 1, 2009 at 12:47 PM, Ondrej Certik<ond...@certik.cz> wrote:
> After your feedback to the coverage script and some discussion, I plan
> to impose a rule on all new code, that all new methods/functions must
> pass the coverage test, e.g. there must be at least one example
> doctest. Just like Sage has, but the difference here is that we don't
> use doctests for testing the code --- use regular tests in the test/

This thread is relevant if you want to know what Sage is doing and why:

http://groups.google.com/group/sage-devel/browse_thread/thread/9eecfe0599911c27

Ondrej

[Ryan Krauss]

I think this is great.  It raises the bar some for contributors, but it greatly improves the resulting code and makes learning and contributing to sympy easier in the long run.

[Ondrej Certik]

On Wed, Jul 1, 2009 at 3:38 PM, Ryan Krauss<ryan...@gmail.com> wrote:
> I think this is great.  It raises the bar some for contributors, but it
> greatly improves the resulting code and makes learning and contributing to
> sympy easier in the long run.

I don't think it raises the bar much, most new contributors usually
fix a function or something, see e.g. the last 14 patches, that I just
merged, not a single one introduces a new function/method (well, only
mine:).

And if your patch is such, that it introduces a new function, then
it's not a big deal to write a doctest.

Ondrej