Ask Your Question

how to contribute tutorial/notebook guide?

asked 2014-07-05 08:57:29 -0500

smbelcas gravatar image

I'm nearly done writing a notebook that gives an overview of the Sage polytope commands for people who want to compute a la Gr\"unbuam / Brondsted.

Is there a standard way to make this available to the community? Of course I can just post it on my webpage, but people are less likely to find it there than if it's somehow in some repository somewhere. (True?)

edit retag flag offensive close merge delete


Clarification: I'm talking about a notebook, not a tutorial. I know there are repositories of things---but not how to find them. Example: Sometime in the past I was given a link to some @interacts for stuff like Euler's Method implementation---wait, google found that again---it's at there must be some central place people can go to find code... right? (No, I know that's probably too much to hope for. But where are people *supposed* to go to find code?)

smbelcas gravatar imagesmbelcas ( 2014-07-05 15:49:45 -0500 )edit

2 answers

Sort by ยป oldest newest most voted

answered 2014-07-05 16:29:35 -0500

kcrisman gravatar image

I'd use sws2rst for a start in converting it to a thematic tutorial. I understand your reticence to go all the way to doing so if you only have a notebook worksheet, but unfortunately there is (currently) no centralized repo for such things. (And a thematic tutorial, or just tutorial, actually probably is appropriate - perhaps the "thematic tutorial" name is not appropriate?)

More importantly, they are not available to people using the command line or just browsing the web without using the notebook or importing them to the cloud. One easier thing to do is for you for now is to post a link to somewhere on the internet with the raw file, and we could open a Trac ticket for adding this somewhere in the documentation.

edit flag offensive delete link more


Now that I have a thematic tutorial (in need of some finessing), what do I do with it?

smbelcas gravatar imagesmbelcas ( 2014-07-09 09:39:02 -0500 )edit

And (metaquestion) what do I do with the directions I wrote for how to make tutorials?

smbelcas gravatar imagesmbelcas ( 2014-07-09 09:39:42 -0500 )edit

For now, you could post a link (or send someone working with Sage such a link) to the documents you have created and ask them to open Trac tickets for including these items. Alternately, you could acquire a Sage Trac account (see for details) and do so yourself, though that would be a few extra steps that may seem onerous. The latter seems especially useful.

kcrisman gravatar imagekcrisman ( 2014-07-09 13:48:50 -0500 )edit

answered 2014-07-05 13:08:48 -0500

The documentation that is attached to the Sage distribution consists of the reference manual, the developers manual, and a collection of thematic tutorials. Your subject obviously fits the latter. All such Sage documentation is written in a format understandable by Sphinx, the tutorials mostly are in RST format. Please see the developers manual on how to write tutorials, and how to contribute them to Sage. A helpful tool to convert e.g. LaTeX into RST or many other formats is the highly recommended Pandoc program.

edit flag offensive delete link more


This was not a very helpful response. First, it didn't tell me where to find the developer's manual. (Google answered that for me.) Second, it didn't tell me where in the developer's manual to find instructions---the table of contents doesn't list such a thing. But third and most importantly, I'm not writing a "thematic tutorial" as in the documentation. Personally, I find those unhelpful. What I've written is a notebook. And what I find helpful are notebook-like things, of which I know there are repositories somewhere because at various points Sage folk have directed me to them.

smbelcas gravatar imagesmbelcas ( 2014-07-05 15:45:09 -0500 )edit

@rws, is there a place in the developer guide where how to write tutorials is discussed? That may need to be a little more prominent.

kcrisman gravatar imagekcrisman ( 2014-07-09 13:49:40 -0500 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools

1 follower


Asked: 2014-07-05 08:57:29 -0500

Seen: 174 times

Last updated: Jul 05 '14