Sphinx and the Sage Documentation
Mike Hansen
Carl Witty and I wrote a proposal for the use of the Sphinx
documentation system in Sage. It can be found at
http://wiki.sagemath.org/SphinxSEP We'd appreciate any comments /
questions / concerns that people have.
--Mike
David Philp
The documentation system I want to see is a centralised wiki. It
works like this:
help(var) gets you the [locally cached] copy of the documentation.
You read it and think "that documentation sucks" or "this needs a few
more see-also-links", you click the "edit me" link and you get taken
to the relevant web page and improve it for everyone.
I don't know how compatible or exclusive that is with sphinx. But I
reckon it would be a good way of obtaining user-centric documentation.
D
Mike Hansen
> works like this:
> help(var) gets you the [locally cached] copy of the documentation.
I think these are two orthogonal problems. Do you mean something like
this http://sd-2116.dedibox.fr/pydocweb/wiki/Front%20Page/ ?
--Mike
David Philp
They are orthogonal but you might think about them at the same time.
By the look of it, that is like what I meant. Basically, every time I
find myself looking at a manpage, I am thinking "I've read this
before, but how..." I then think "I wish this was wikipedia so I
could put the example in until someone comes up with a better one."
That's the problem I want fixed. I think it arises because developers
of software packages tend to write documentation for themselves, so
every documentation page tends to read like an interface specification
rather than providing pedagogical examples and "you might be looking
for XYZ" links. Sage is already better than some others.
I certainly don't have time to do it. If someone likes the idea
please run with it!
D
Alec Mihailovs
united.
What I miss in the documentation, is index and search (not just one
document, but all of them), as in Windows chm files.
Alec
John H Palmieri
On Aug 21, 5:35 pm, "Mike Hansen" <mhan...@gmail.com> wrote:
> Hello all,
>
> Carl Witty and I wrote a proposal for the use of the Sphinx
>
> --Mike
so I can try it out? From <http://sphinx.pocoo.org/latest/
index.html>, for example, which says the latest version is 0.5, it
says "Get Sphinx from the Python package index", and when I follow
that link, I get to a page where I can download 0.4.2, which doesn't
(as far as I can tell) have the math stuff in it.
John
Mike Hansen
> so I can try it out?
You can do an SVN checkout from http://svn.python.org/projects/doctools .
I played around a bit with converting the tutorial this evening and
here are the results using the PNG images for the HTML output. There
are still some artifacts left from the conversion that need to be
cleaned up:
http://sage.math.washington.edu/home/mhansen/sphinx-tutorial/index.html
http://sage.math.washington.edu/home/mhansen/Sage.pdf
--Mike
William Stein
This is from the guy organizing a lot of the transition of the
numpy docs over to Sphinx...
---------- Forwarded message ----------
From: Stéfan van der Walt <sjvd...@gmail.com>
Date: Fri, Aug 22, 2008 at 1:00 AM
Subject: Re: [sage-devel] Re: Sphinx and the Sage Documentation
To: William Stein <wst...@gmail.com>
Hey William,
They can always use the source tree:
Development branch:
URL: http://svn.python.org/projects/doctools/branches/0.4.x
Stable branch:
URL: http://svn.python.org/projects/doctools/trunk
Could be the other way around, not sure.
I'll take a look at the proposal, thanks for bringing it to my attention!
Cheers
Stéfan
2008/8/21 William Stein <wst...@gmail.com>:
> William Stein
> Associate Professor of Mathematics
> University of Washington
> http://wstein.org
>
--
William Stein
Associate Professor of Mathematics
University of Washington
http://wstein.org
Ondrej Certik
+1
I am missing this too. Also don't have time to fix it.
Ondrej
Martin Albrecht
I skimmed through the docs and I'm pretty sure by now: I want it :-)
A lot of stuff is there (like citations) already, it is used by a critical
mass of projects and it ends the time of reinventing the wheel for us in that
area.
So +1 from me (even though I know no official vote is taken yet)
Martin
--
name: Martin Albrecht
_pgp: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x8EF0DC99
_www: http://www.informatik.uni-bremen.de/~malb
_jab: martinr...@jabber.ccc.de
Ondrej Certik
<ma...@informatik.uni-bremen.de> wrote:
>
>> Carl Witty and I wrote a proposal for the use of the Sphinx
>> documentation system in Sage. It can be found at
>> http://wiki.sagemath.org/SphinxSEP We'd appreciate any comments /
>> questions / concerns that people have.
>
> I skimmed through the docs and I'm pretty sure by now: I want it :-)
>
> A lot of stuff is there (like citations) already, it is used by a critical
> mass of projects and it ends the time of reinventing the wheel for us in that
> area.
>
> So +1 from me (even though I know no official vote is taken yet)
I am +1000, because I hope some of you will implement the latex
printing in sphinx and thus I will benefit. :)
Ondrej
William Stein
+1 from me too because:
* this Sphinx thing is clearly the direction the python community
is going. The *only* reason sage uses its current latex/latex2html
system is because that's precisely what Python officially used
when I started sage. We should change with Python.
* there are numerous tools -- for example a collaborative wiki environment
for documentation -- that are being developed for Sphinx. It might
be great to leverage these.
William
John H Palmieri
> I played around a bit with converting the tutorial this evening and
> here are the results using the PNG images for the HTML output. There
> are still some artifacts left from the conversion that need to be
> cleaned up:
>
> http://sage.math.washington.edu/home/mhansen/sphinx-tutorial/index.htmlhttp://sage.math.washington.edu/home/mhansen/Sage.pdf
is good, but then the math didn't look that good in the latex2html
version, either. You can probably tweak some things to make it look
better (e.g., wherever you have $x$, replace it with *x* instead
of :math:`x`), just the way you can with latex2html.
My guess, from looking at the Sphinx documentation (and from the fact
that you produced this so quickly) is that most of the documentation
will be easy to convert, with a combination of regexp search-and-
replace, macros, and editing by hand. The real work will be in the
reference manual, since that's autogenerated, and no one is going to
want to go through all of the source code, changing all of the latex
to reStructuredText.
Overall, though, switching to Sphinx seems like a fine idea.
John
> --Mike