On Oct 2, 2009, at 1:46 AM, Dag Sverre Seljebotn wrote: > Peter Alexander wrote: >> >> 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.
It almost sounds like you want a big glorified index. (I'm not saying that's a bad thing, and it certainly would fit your bill of being able to look stuff up fast.) > 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. We do that in Sage and it works very well--the reference manual is thousands of pages long, nearly all from function docstrings. > 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 ... > """ No offense intended (as this was clearly marked as an experiment) but I have to admit this feels rather contrived, especially if we end up making classes/structuring code just to hold the docstrings of user- level abstractions. I think it would lead to a sparse scattering of documentation throughout the codebase (most of the code does *not* need to be exposed to the user documentation, e.g. all the Nodes that represent Python nodes, and most transforms). The comments/doctests in the code should probably be about the code itself (useful to a cython developer, but probably not to a cython user). - Robert _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
