Dag Sverre Seljebotn wrote: > Robert Bradshaw wrote: > >> On Oct 1, 2009, at 9:46 PM, Peter Alexander wrote: >> >> >>> ..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. > 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. A link to matplotlib's Sphinx extensions:
http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/lib/matplotlib/sphinxext/plot_directive.py?view=markup http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/lib/matplotlib/sphinxext/ Longwinded example of what could be done. """ Simple demo ========= .. cython:: :name: example2 :hidden: True # This stuff is not shown in docs as people's got used to them being there by # this point in the tutorial. However it ends up in the generated "example2.pyx". cimport cython # Other blocks with the same name are appended later. We start with making a function: .. cython:: :name: example 2 def myfunc(x): return x * 2 This is now available from Python: .. pythonshell:: >>> import example2 >>> example2.myfunc(2) .. Note that above we don't need to enter output, that is generated by Sphinx. However, a cdef function is not available: .. cython:: :name: example2 cdef mycdef(x): return x * 2 .. pythonshell:: :continue: True >>> example2.mycdef(3) """ In the end, example2.pyx and setup.py is generated by concatenating the chunks and offered for download. _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
