On Sat, Nov 14, 2009 at 2:20 PM, John H Palmieri <jhpalmier...@gmail.com> wrote: > > 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
(1) Almost all of the docstrings in Sage look like this: INPUT: - `n` - an integer - `m` - another integer - `k` - a third integer, with a longer description with spaces. I'm not sure why, but I think Mike Hansen argued that he had to do things this way when he was transition from our old non-Sphinx docs. Evidently Sphinx has changed since then (or he was wrong). (2) Regarding your example: """ INPUT: - n - an integer - m - another integer - k - a third integer, with a longer description """ I just want to point out that the space before the "longer" above is *critical*. Moreover, it has to be at least *two* spaces, i.e., the start of the word "longer" has to line up with the "k" above (your example maybe didn't). > > 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. My impression is that it was in exactly the way that is being discussed in this thread. The way Jarrod put it was "we need a Bibtex for Sphinx", i.e., a way to have a database of references that is separate from the individual docstrings. That's basically the same problem being discussed in this thread. > >> 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? Problem = the lack of a "Bibtex for Sphinx". > 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. My understanding is that the problem is that nobody has yet written something like Bibtex for Sphinx. That's a bit of a different problem than just changing syntax. How would you write large latex papers/books without Bibtex? Ick. -- William --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
