On Fri, Oct 2, 2009 at 4:46 AM, Dag Sverre Seljebotn <[email protected]> wrote: > Peter Alexander wrote: >> 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. >> > OK, I see where you are coming from. As usual my suggestions are mostly > with tutorials in mind. > > Other projects can do this in a great way by making the docstrings in > the codebase their chunks. That doesn't *quite* all the time with > Cython, but I think it could work great in some types of situations. > > Experiment: > > class WraparoundDirective(CompilerDirective): # in Options.py > """ > wraparound > > information about the wraparound compiler directive > """ > > class ForInStatNode(Node): # In Nodes.py > """ > Python-style for-loop > > more info > > TAGS: pythoncompatible, loops > """ > > > Some transforms would fit for documenting language features as well: > > class ForloopOptimizations(CythonTransform): > """ > Optimizations done to for-loops: > > - for in range is ... > """ > > > Then, a pragmatic, non-pure "documentation structure model" could simply > be ReST documentation with some codes for grabbing the chunks from the > codebase: > > .. docstring:: ForInStatNode > > or perhaps > > .. docstring-table:: > :subclassesof: CompilerDirective > > .. docstring-table:: > :tag: pythoncompatible > > Dag Sverre > _______________________________________________ > Cython-dev mailing list > [email protected] > http://codespeak.net/mailman/listinfo/cython-dev >
Is this a practical and like-able idea? should we investigate going along this route? I'm gonna look into making custom sphinx directives, which I haven't done before.. look at what numpy, matplotlib and others are doing with custom directives. I feel we should seriously consider it over a pita to upkeep, one-off doc creation scenario. More comments most welcome.. :) _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
