On Nov 14, 2:38 pm, William Stein <wst...@gmail.com> wrote:
>
> (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).
It may not have changed, maybe double-spacing was just the best way to
do his automatic conversion all of the old docstrings to the new
format without causing too many problems. I don't know.
> (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).
Right, this is what I get for typing in a non-fixed-width font.
> 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.
> 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.
Well, maybe what we need is this: in each module, class, whatever, we
keep doing what we're doing:
{{{
See the paper [Mil] for more details.
REFERENCES:
- [Mil] John W. Milnor, "The Steenrod algebra and its dual" ...
}}}
and then we also append to this a Sphinx/reST citation like "[Mil58]_"
which points to a master bibliography file. Then local citations will
still be valid and will point to local references, and there will in
addition be a single place where all of the references are listed.
The local citations ([Mil] or [M] or ...) can also vary (as they do in
some of my code -- sorry, Alex), as long as [Mil] or [M] or whatever
all have the same master citation "[Mil58]_" appended.
If we want to do this, then we need a style guide for what goes in
these master citations; imitating the Bibtex style amsalpha seems like
a fine plan to me.
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
-~----------~----~----~----~------~----~------~--~---
