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.
On Wed, Jul 1, 2009 at 1:47 PM, Ondrej Certik <[email protected]> wrote: > > 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 > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sympy" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/sympy?hl=en -~----------~----~----~----~------~----~------~--~---
