On Jul 7, 2009, at 12:16 AM, Ondrej Certik wrote:
>
> On Mon, Jul 6, 2009 at 9:56 PM, Aaron S. Meurer<[email protected]>
> wrote:
>>
>> Well, it took me long enough, but I finally have my contribution to
>> doc day finished. I actually had the thing all written up by the end
>> of doc day, but I had to learn how to format it as Sphinx, and how to
>> get the stupid doctests to pass. I ended up skipping some because it
>> wouldn't pass them with pretty printing. I know it is possible to
>> test pretty, because other docs do it, but I couldn't figure out how
>> to change it. I think it defaulted to non-pretty because that is
>> what
>> my first example is. At any rate, if you know how to get those tests
>> to pass, feel free to unskip them. Note that some tests are skipped
>> because they demonstrate exceptions being raised.
>>
>> See issue 1519: http://code.google.com/p/sympy/issues/detail?id=1519,
>> or just pull from http://github.com/asmeurer/sympy/tree/doc-day.
>>
>> I added the gotchas and pitfalls document that I talked about earlier
>> in this thread. I also added a simple Sphinx document for the
>> functions in simplify (just docstrings).
>
> Wow, great work, many thanks!
>
> The patch is good enough to go in, only there is some problem if you
> run all tests with "setup.py test":
>
> ================== tests finished: 236 passed in 4.75 seconds
> ==================
> Testing doc/src/guide.txt
> Failed 0, tested 0
> **********************************************************************
> File "doc/src/gotchas.txt", line 142, in gotchas.txt
> Failed example:
> z**2 # z is not defined yet
> Expected:
> Traceback (most recent call last):
> File "<stdin>", line 1, in <module>
> NameError: name 'z' is not defined
> Got:
> z**2
> **********************************************************************
> 1 items had failures:
> 1 of 90 in gotchas.txt
> ***Test Failed*** 1 failures.
>
Interesting. All tests pass on my machine (I made sure to check
before I pushed). I repushed with that test skipped.
>
> apparently something has defined "z". I think we need to improve our
> doctesting runners to strictly reset the namespace.
I think we should reset the namespace but still allow only one "from
sympy import *" at the top. Maybe we could "from sympy import *" and
maybe "x, y, z = symbols('xyz')" automatically. Just an idea.
Is there a way to do invisible comments in Sphinx? If so, we could
imbed more advanced options in them. Again, just an idea.
>
> There is a way to fix pretty printing doctesting, I'll try to look
> into it if noone can figure it out.
If you think you can fix any skipped tests that would be great. If
anything, those "#doctest: +SKIP" lines make the file look ugly.
>
> As to testing exceptions, just use "...", see:
>
> http://docs.python.org/library/doctest.html#doctest.ELLIPSIS
I'm not sure how this is supposed to work. Like I said, the test
passed on my machine as they were.
Autodoc is also problematic, especially in the limitations that it
imposes on docstrings. For example, the following line (from
Basic.new) rasies a warning because it interprets the * as an
unmatched emphasis symbol:
type(self) (*args)
Fortunately, it only raises warnings once, so they can be ignored.
Unfortunately, it fails severe if you try to use certain other Sphinx
formatting in docstrings, such as placing ='s under a header title.
>
> Ondrej
Aaron Meurer
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
