On Nov 14, 1:55 pm, William Stein <wst...@gmail.com> wrote: > On Fri, Nov 13, 2009 at 11:18 PM, Robert Bradshaw > > <rober...@math.washington.edu> wrote: > > > This is one of the many, many cases where I think it would be easier > > to fix the tool rather than change people's behavior. Why not have our > > cake and eat it too? [ABC] can automatically be turned into [ABC]_ > > (perhaps only if it matches something below). Global name conflicts > > can automatically be resolved, either by picking the first (if they're > > "close enough") or making them unique. The REFERENCES section can be > > stripped if its empty. > > > I reallly like ReST, and it's a huge step ahead of what we used to > > have, but (and I've said this before) in many ways using raw ReST > > seems like a step backwards (double ::'s for doctests, ` for math > > mode, double-spacing function argument specs, etc.)
(a) You need double ::'s for verbatim blocks to be processed correctly for the documentation output. For locating doctests, as long as it's indented, I don't think it matters whether there are any colons at all. You can check that doctests from old files which haven't been sphinxified (and so which have single colons) are still being run. (b) For math mode, you can use $ now. (c) I don't know what you mean about double-spacing function argument specs. You can write INPUT: - n - an integer - m - another integer - k - a third integer, with a longer description Or you can write INPUT: :param n: an integer :param m: another integer :param k: a third integer, with a longer description > I strongly agree with this. In fact, last week when I was hanging out > with Jarrod Millman (of scipy/numpy), he baited me -- "so, are you > guys using Sphinx a lot for Sage yet?" When I said "yes!", he > responded, "so how did you guys solve the references problem, since > references are a total mess in Sphinx?" And said that we hadn't yet. In what way are they a total mess? I'm curious. > Of course, it was inevitable that we would run head first into this > problem eventually, and it's amusing that we did this week. > > Anyway, I agree with Robert -- to solve this particular problem we > will have to go creatively beyond what Sphinx offers "out of the box". Which particular problem? Alex just pointed out that we haven't been using standard Sphinx/reST for citations, and we should. That's easy to solve "in the box". More generally, we don't use pure Python in Sage -- we've changed it so that ^ means exponentation -- but it's pretty close to pure, and it seems that we're reluctant to change it much. I feel the same way about Sphinx or reST: it seems like a bad idea to just change it when we happen to not like the syntax. Sage is a computer program, and it is reasonable to ask people to learn Python syntax to write Sage programs, and I think it is also reasonable to ask people to learn reST to write docstrings. It's not that hard, and it makes our docstrings portable. John --~--~---------~--~----~------------~-------~--~----~ To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel-unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
