sage -rst2html and sage -rst2sws would be nice!

[slabbe]

Hi sage-devel,

I am more an more using .rst files for myself and I am thinking of
implementing new scripts that I think would be usefull. Below I
describe what are those commands. I still don't know exaclty how to
code them, so if you have any ideas, suggestions I'm interested.

==============
sage -rst2html
==============

It would be nice to implement the command:

sage -rst2html input.rst output.html

that would convert a rst file into a html file like does the usual
command:

rst2html.py input.rst output.html

but using the defaults roles for Sage documentation, i.e. `text in
single backquotes` interpreted as latex and recognizing other macros
like `\ZZ`.

My ideas
--------

After reading on ReStructuredText, docutils and sphinx, I understand
that different roles can be given to interpret text
inside :role:`single backquotes`. The package docutils allows to
translate .rst file into plenty of other format and defines the
following commands :

rst2html.py rst2odt.py rst2xml.py
rst2latex.py rst2odt_prepstyles.py rstpep2html.py
rst2man.py rst2pseudoxml.py
rst2newlatex.py rst2s5.py

Although, the math role is not part of docutils:

$SAGE_HOME/local/lib/python2.6/site-packages/docutils/parsers/rst/
roles.py

The math role is implemented in sphinx:

$SAGE_HOME/local/lib/python2.6/site-packages/Sphinx-0.6.3-
py2.6.egg/sphinx/roles.py
$SAGE_HOME/local/lib/python2.6/site-packages/Sphinx-0.6.3-
py2.6.egg/sphinx/ext/mathbase.py
$SAGE_HOME/local/lib/python2.6/site-packages/Sphinx-0.6.3-
py2.6.egg/sphinx/ext/pngmath.py

Definition of default macros like `\ZZ` are here:

$SAGE_HOME/devel/sage/sage/misc/latex_macros.py
$SAGE_HOME/devel/sage/doc/common/conf.py

So, maybe I am not far from the solution. How to give the information
about roles and macros to the rst2html command? Maybe also somebody
who already worked on it can help me...

=============
sage -rst2sws
=============

As I prefer to edit text files but still like the Sage Notebook to
give presentations, it would be really nice to implement the command:

sage -rst2sws demo.rst demo.sws

Of course, in this case, the docutils package does not provide the
command rst2sws. Right now, there is a way do it (Nicolas Thiéry and
Florent Hivert both use this trick) through the Sage Documentation
Docbuild system:

1. Copy the .rst file in the directory $SAGE_HOME/doc/en/reference/
demos
2. Add a link to it in the file $SAGE_HOME/doc/en/reference/index.rst
3. Recompile the documentation ``sage -docbuild reference html``
4. Open the Sage Notebook
5. Open the dynamic version of the documentation
6. Go in the demo section of the Reference Manual
7. Open the initial file in the notebook

So the question is : How far are we from having a command `sage -
rst2sws` ? or from being able to upload a Sage Worksheet from a .rst
file? Do you have any clue in order to create such a command/
functionality?

Thank you,

Sébastien Labbé, Montréal

[Dan Drake]

Hello Sebastian,

On Mon, 06 Dec 2010 at 08:50AM -0800, slabbe wrote:
> ==============
> sage -rst2html
> ==============
>
> It would be nice to implement the command:
>
> sage -rst2html input.rst output.html
>
> that would convert a rst file into a html file like does the usual
> command:
>
> rst2html.py input.rst output.html
>
> but using the defaults roles for Sage documentation, i.e. `text in
> single backquotes` interpreted as latex and recognizing other macros
> like `\ZZ`.

[...]

> =============
> sage -rst2sws
> =============
>
> As I prefer to edit text files but still like the Sage Notebook to
> give presentations, it would be really nice to implement the command:
>
> sage -rst2sws demo.rst demo.sws
>
> Of course, in this case, the docutils package does not provide the
> command rst2sws. Right now, there is a way do it (Nicolas Thiéry and
> Florent Hivert both use this trick) through the Sage Documentation
> Docbuild system:

This reminds me of Rob Beezer's TeX-to-sws converter. Both of your
scripts sound like good ideas -- I'd like to see more tools that make it
easy to write about Sage. File some trac tickets!

Dan

--
--- Dan Drake
----- http://mathsci.kaist.ac.kr/~drake
-------