On Fri, Oct 2, 2009 at 4:16 AM, Dag Sverre Seljebotn <[email protected]> wrote: > 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 >
Putting my creative hat on... Would be nice to just be able to toss "chunks" of information into a directory pool, that can be automatically structured to a view, by a "documentation structure model"? That way upkeep could be made more simple because all you'd have to worry about is tossing in the "chunk". That's kind of what I mean by an MVC model. _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
