On Oct 2, 2009, at 12:59 AM, Dag Sverre Seljebotn wrote: > Robert Bradshaw wrote: >> On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: >> >>> "User Guide" would essentially be the reference guide outline but in >>> paragraph form which includes more detailed info, caveats, gotchas. >>> This would help keep the ref guide succinct in that "detail" can be >>> linked to from that document to this document (as well as tutorial >>> sections, etc..) >> >> This section seems redundant with tutorial + reference guide. >> > I think that it would not be entirely redundant; some other projects > have user guides and it tends to work well. However it is a > question of > how much we are able to do -- even creating it is a lot of work, but > (much worse) then it has to be maintained for years to come too. > > So I agree that we should avoid this one, at least until the other > points on the list are done.
I should clarify--I imagine our "tutorials" to have somewhat of a users guide feel (as opposed to a task solving feel). > The matplotlib project has very good experience with some exciting > stuff > that's kind of related (their entire web page is made with Sphinx). > They > wrote a plugin to sphinx for a new code block tag (in the rst file in > the documentation). When encountered, Sphinx a) presents the code as > syntax-highlighted Python, b) executes the code and retrieves the > generated plot and present it. > > By adapting such a plugin for our needs, a special tag can be used to > embed Cython code, which at least syntax-highlights and makes "cython > -a" easily available; perhaps also presents a link to a Sage worksheet > with the code. Automatically benchmarking Cython examples comes to > mind > too and would make it easier to write tutorials etc (although that > means > documentation must be rebuilt under benchmark conditions (no other > load, > always rebuild everything on the same machine) which is a serious > drawback). > > The great thing is that everything stays in the ReST documents and is > easily rebuildable. That sounds nice. > I must say I'm really keen on having code snippets embedded into ReST > text (and rather automatically exported as files), rather than the > other > way around. Me too. I like your example of using :hidden and constructing whole files--I didn't know you could do that. Sounds perfect (for the tutorials at least). - Robert _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
