#10637: Implement sage -sws2rst
------------------------------------------------------------+---------------
Reporter: nthiery | Owner:
jason, mpatel, was
Type: enhancement | Status:
needs_review
Priority: major | Milestone:
sage-5.1
Component: notebook | Resolution:
Keywords: ReST, worksheet | Work issues:
Report Upstream: Workaround found; Bug reported upstream. | Reviewers:
Nicolas Thiéry, Jason Grout, Karl-Dieter Crisman, Jason Bandlow
Authors: Pablo Angulo, Karl-Dieter Crisman | Merged in:
Dependencies: #11080 | Stopgaps:
------------------------------------------------------------+---------------
Comment (by kcrisman):
'''WOW!!! ''' This is really awesome! I did a moderately complicated
worksheet just now, and had only one error message.
{{{
: WARNING: Bullet list ends without a blank line; unexpected unindent.
}}}
This was in a sublist. Here is the html source in `sage_worksheet`.
{{{
<p>This works because Sage is very collaborative. </p>
<ul>
<li>Anyone who has access to the server can be invited to share a
document.</li>
<li>In this case, the teacher would post a lab, and the students could
share a copy of it with each other to work on it.</li>
<li>Then, when they are done, they can:
<ul>
<li>Publish it to the server for the teacher to view, or </li>
<li>Share it with the teacher, or </li>
<li>Download it to be uploaded by the teacher...</li>
</ul>
</li>
</ul>
}}}
I don't know whether this is 'needs work' or for a future ticket, since it
still looks right in the built Sphinx output.
Also, along the same priority lines, if you include jpg images in the data
directory, I guess they don't always look quite right - that is, they
don't scale with the size of the picture. I guess that is just because
they are jpg files, not png - probably there is no real solution to this.
The graphics from Sage do fine.
----
More importantly, I think that there we need to add some documentation as
to how to use this somewhere. What do you think? I think that
[http://sphinx.pocoo.org/tutorial.html the Sphinx tutorial] in conjunction
with the following would do it.
* To turn a worksheet into nice documentation outside the Sage doc tree,
first make a folder somewhere convenient labeled (say) `MyProject`.
* Then move your `.sws` file into that folder, and cd into it.
* Now the key is to use Sage's shell to run Sphinx on it! Run `sage -sh`
here.
* Now type `sphinx-quickstart` and follow the instructions in the Sphinx
tutorial. you will probably want to render math with MathJax.
* If you now type `make html` you should get a beautiful-looking web page
in `_build/html`. Other things like `make pdf` will do the same.
Here's another thing. As far as I can tell, one can pretty much only run
this on an `.sws` that is in the directory you live in. So we need to
document this in the same place.
----
So here are the issues for 'needs work'.
* Make `sage -sws2rst` fail gracefully if one hasn't installed the
beautifulsoup spkg. Naturally, this requires beautifulsoup to be an
optional or at least experimental spkg. Since it's just a Python thing,
that shouldn't be a problem.
* Add documentation. This doesn't need to be intense.
* Somehow we have to resolve this issue with the older worksheets (if it
is in fact an issue).
* Figure out how to deal with the case where there are no `cells/` in the
worksheet for some reason.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10637#comment:45>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
