On Tue, Jul 7, 2009 at 12:48 AM, Aaron S. Meurer<[email protected]> wrote: > > 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.
Here is an example: http://certik.github.com/python-theora/module_theora.html#theora.Theora.get_frame_image (see the repr statement with "..." instead of the memory address of the instance) and here: http://certik.github.com/python-theora/module_theora.html#theora.TheoraEncoder.fix_size is an example of using "..." to handle exceptions. > > 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. Just add one more ":" at the end of the previous line to tell sphinx to interpret the next block as a code block. > Unfortunately, it fails severe if you try to use certain other Sphinx > formatting in docstrings, such as placing ='s under a header title. We can use different ways to create headers in the docs, then we can use "=" in docstrings. Another way is to preparse the docstrings, like numpy is doing. 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 -~----------~----~----~----~------~----~------~--~---
