Proposal for Inclusion into Sage: Sphinx, Docutils, Pygments, and Jinja
Mike Hansen
As part of the conversion of the Sage documentation to Sphinx, I
propose that Sphinx and its dependencies (Docutils, Pygments, and
Jinja) be added to Sage. Here are brief descriptions for what each of
the packages does:
* Sphinx is a tool that makes it easy to create intelligent and
beautiful documentation for Python projects (or other documents
consisting of multiple reStructuredText sources), written by Georg
Brandl. It was originally created to translate the new Python
documentation, but has now been cleaned up in the hope that it will be
useful to many other projects.
* Docutils is a modular system for processing documentation into
useful formats, such as HTML, XML, and LaTeX. For input Docutils
supports reStructuredText, an easy-to-read,
what-you-see-is-what-you-get plaintext markup syntax.
* Pygments is a syntax highlighting package written in Python. It is
a generic syntax highlighter for general use in all kinds of software
such as forum systems, wikis or other applications that need to
prettify source code. Highlights are: a wide range of common languages
and markup formats is supported, special attention is paid to details,
increasing quality by a fair amount, support for new languages and
formats are added easily, a number of output formats, presently HTML,
LaTeX, RTF, SVG and ANSI sequences, it is usable as a command-line
tool and as a library.
* Jinja is a sandboxed template engine written in pure Python. It
provides a Django like non-XML syntax and compiles templates into
executable python code. It's basically a combination of Django
templates and python code.
While all of the above are required for Sphinx, some of them also
provide other advantages to Sage. For example, pygments can be used
to provide syntax highlighting in trac, the wiki, and the Mercurial
code browser. Docutils would allow one to use reStructuredText within
the wiki. The Jinja templating system would be very useful in the
notebook to help separate the HTML / CSS / Javascript from the Python
code and provide greater consistency and extensibility though things
like internationalization of the templates.
All of the above are released under the modified BSD license and are
pure Python packages which should be trivially portable to any of
Sage's target platforms. Spkgs for all of the above can be found at
http://sage.math.washington.edu/home/mhansen/doc-sphinx/ . The order
they should be installed in is setuptools, pygments, docutils, jinja,
and sphinx.
VOTE:
[ ] Yes, include these in Sage
[ ] No, do not (please explain)
[ ] Hmm, I have questions (please ask).
Thanks,
Mike
David Joyner
>
> Hello all,
>
> As part of the conversion of the Sage documentation to Sphinx, I
> propose that Sphinx and its dependencies (Docutils, Pygments, and
> Jinja) be added to Sage. Here are brief descriptions for what each of
> the packages does:
>
...
>
>
> VOTE:
> [ ] Yes, include these in Sage
I vote yes
Alex Ghitza
VOTE:
[ ] Yes, include these in Sage
[ ] No, do not (please explain)
[ ] Hmm, I have questions (please ask).
Alex Ghitza -- Lecturer in Mathematics -- University of Melbourne -- Australia
mabshoff
On Sep 29, 4:16 pm, "Mike Hansen" <mhan...@gmail.com> wrote:
> Hello all,
<SNIP>
> All of the above are released under the modified BSD license and are
> pure Python packages which should be trivially portable to any of
> and sphinx.
>
> VOTE:
> [ ] Yes, include these in Sage
> [ ] No, do not (please explain)
> [ ] Hmm, I have questions (please ask).
>
> Thanks,
> Mike
for the other four spkgs. I will start reviewing the spkgs tonight.
Cheers,
Michael
William Stein
--
William Stein
Associate Professor of Mathematics
University of Washington
http://wstein.org
Nick Alexander
Yes!
Nick
Robert Bradshaw
> Hello all,
>
> As part of the conversion of the Sage documentation to Sphinx, I
> propose that Sphinx and its dependencies (Docutils, Pygments, and
> Jinja) be added to Sage. Here are brief descriptions for what each of
> the packages does:
>
[...]
> VOTE:
> [X] Yes, include these in Sage
> [ ] No, do not (please explain)
> [ ] Hmm, I have questions (please ask).
IMHO, all of these will be very nice to have. One question I have is
about size. Are we talking 100k each, or tens of megabytes?
- Robert
Mike Hansen
> IMHO, all of these will be very nice to have. One question I have is
> about size. Are we talking 100k each, or tens of megabytes?
The spkgs that I made range from 200k to 1.1m for a total of about
2.5mb. There is definitely room to slim these down if needed.
--Mike
Robert Bradshaw
For the functionality provide, I think that's slim enough.
- Robert
mabshoff
are definitely worth it since it makes the documentation trivially
buildable without any external dependencies. The current setup with
latex2html is just a giant pain for people interested working on the
documentation. The new toolchain is also significantly (read orders of
magnitude) faster. Since it also looks much better and is also the new
Python documentation toolchain I think we can only win here. It even
allows highlighted help in the notebook in true html :)
> --Mike
Cheers,
Michael
Jason Grout
> <mailto:mha...@gmail.com>> wrote:
>
>
> VOTE:
> [ ] Yes, include these in Sage
> [ ] No, do not (please explain)
> [ ] Hmm, I have questions (please ask).
Yes.
Jason
didier deshommes
> [ ] Yes, include these in Sage
> [ ] No, do not (please explain)
> [ ] Hmm, I have questions (please ask).
+1, and a question. As far as I know, pygments doesn't have
syntax-highlighting for pyrex files. If you wrote your own, it would
be nice if you could contribute back to the pygments project :)
see http://dev.pocoo.org/projects/pygments/ticket/359
didier
mhampton
> VOTE:
> [X ] Yes, include these in Sage
This makes sense on its own merits; I also believe that it makes sense
to move as much as possible to python-based tools, and this is great
from that point of view.
Marshall Hampton
Carl Witty
> Hello all,
>
> As part of the conversion of the Sage documentation to Sphinx, I
> propose that Sphinx and its dependencies (Docutils, Pygments, and
> Jinja) be added to Sage.
[X] Yes, include these in Sage
Carl
Jason Grout
> Hello all,
>
> * Jinja is a sandboxed template engine written in pure Python. It
> provides a Django like non-XML syntax and compiles templates into
> executable python code. It's basically a combination of Django
> templates and python code.
>
Is this Jinja 1 or Jinja 2? If Jinja 1, why not version 2?
Thanks,
Jason
Mike Hansen
On Mon, Sep 29, 2008 at 9:20 PM, Jason Grout
<jason...@creativetrax.com> wrote:
> Is this Jinja 1 or Jinja 2? If Jinja 1, why not version 2?
This is Jinja 1.2 since that is what is required by Sphinx. They're
planning on switching over to Jinja2 once they feel it has matured
enough: http://groups.google.com/group/sphinx-dev/browse_thread/thread/2d4fae9476006ad1/67a62b45fa1ed651?lnk=gst&q=jinja+2#67a62b45fa1ed651
--Mike
Martin Albrecht
[X] Yes, include these in Sage
Cheers,
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
Dag Sverre Seljebotn
announced:
"""
* Basic Pygments Cython highlighter (still some bugs, but I will iron them
out), so Cython is highlighted!
"""
So this is already on the way. (CCing Gabriel on this + mentioning it so
that Sage doesn't duplicate the effort.)
Dag Sverre
Robert Miller
William Stein
Just out of curiosity, if one wanted to write a *math* paper
using Sphinx, what would happen? How would it "feel"?
How contorted would the experience be?
William
On Tue, Sep 30, 2008 at 9:52 AM, Robert Miller <rlmil...@gmail.com> wrote:
>
> [X] Yes, include these in Sage
>
> >
>
--
Mike Hansen
On Tue, Sep 30, 2008 at 10:27 AM, William Stein <wst...@gmail.com> wrote:
> Just out of curiosity, if one wanted to write a *math* paper
> using Sphinx, what would happen? How would it "feel"?
> How contorted would the experience be?
One would run the sphinx-quickstart script to create a new 'project'
for the paper. That sets up the configuration files and writes some
Makefiles to use for building the docs. Once you set the default role
to math mode so that you can do `2+2` instead of :math:`2+2`, then I
don't think it'd be too bad. It also depends on how many
LaTeX-specific things you usually use in your math papers.
The generated PDF probably wouldn't be exactly what you'd want in
terms of layout / structure, but the HTML wouldn't be too bad.
--Mike
John H Palmieri
mabshoff
On Sep 30, 3:23 pm, John H Palmieri <jhpalmier...@gmail.com> wrote:
> [X ] Yes, include these in Sage
and none against it, so I consider this vote positive.
Cheers,
Michael
cesarnda
ggellner
> > syntax-highlighting for pyrex files. If you wrote your own, it would
> > be nice if you could contribute back to the pygments project :)
>
> On the Cython list, Gabriel Gellner (in charge of Cython documentation)
> announced:
>
> """
> * Basic Pygments Cython highlighter (still some bugs, but I will iron them
> out), so Cython is highlighted!
> """
>
> So this is already on the way. (CCing Gabriel on this + mentioning it so
> that Sage doesn't duplicate the effort.)
>
http://hg.cython.org/cython-docs/file/4657c0c79a6e/sphinxext/cython_highlighting.py
Really it is just a quick hack (all of 10 minutes) on the built in
python highlighter from Pygments.
My plans are:
* highlight cython/pyrex special keywords differently (As requested by
Robert Bradshaw)
* fix the integer loop highlighting
* fix 'extern from highlighting'
Once this is done and it seems to work for a bunch of the docs, I want
to try and get it
upstream for all to enjoy.
Any patches ideas are welcome!
Gabriel