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
