Robert Bradshaw wrote: > On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: > > >> "Tutorials" would be a self contained sphinx doc with a TOC that >> includes tutorials of general, topic and domain specific "dive-in and >> get your hair wet" material. Here we "hold the reader's hand" and walk >> them through usage. >> > > I could see this expanding into the bulk of the documentation, with > 2-4 "getting started" sections, and then numerous independent > chapters after that as previously mentioned in this thread. > > Another option is making tutorials like short "quick starts" with the > bulk of the meat in the reference manual. I'm leaning against this, > but would like feedback. > > >> "Reference Guide" would be an elaborate "outline" of facts. Used for >> fast access to succinct information. >> > > I could see this containing things such as the list of all compiler > directives, syntax particulars, list of builtin types and > optimizations, differences between Python and Cython and other stuff > that does not fit into a tutorial-like nature. Stuff like buffers > should have an entry here, with syntax and a brief overview of how > they work and what they're for, with a link to the tutorial section > for more. How to use them to accomplish different things doesn't seem > to belong in a reference manual. Perhaps gotchas and caviats could go > here too. > > >> "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 think everything else proposed by Peter looks great. >> ..Now, All examples/snippets should be global, in its own directory, >> so each documentation can "embed" the example it needs. Hell.. if we >> were sophisticated one day.. video snippets might also be "embedded" >> or at least linked to. >> > > Does sphinx have the ability to embed external code snippets? I think > it's important to have actual snippets in the documentation itself, > ideally with links to 1. entire working program directories (complete > with build scripts) 2. Annotated (-a html output) versions and 3. > Sage notebooks (to make it easy to try out and play with while you're > reading the documentation) and 4. somewhere that we can run > regression tests on. > 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. An idea for Peter or Minh for now is to at least look into making :cython:: available as a ReST tag and start using it -- even if it has no effect currently, that will make it easier to introduce features like that later on. I'll try to dig up the sources for the matplotlib Sphinx extension. Dag Sverre _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
