On Fri, Oct 2, 2009 at 5:13 AM, Dag Sverre Seljebotn <[email protected]> wrote: > Robert Bradshaw wrote: >> 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). >> >> > You may be right. (The one advantage is that it makes it easy to have > documentation for different versions of Cython.). > > Thing is I need to have some "way of entry" into writing documentation > -- I must either think about the code that implements the feature, or > how I'd "tell people about it" directly in the docs. A pure MVC doesn't > give me that I think -- it would tend to just be another hierarchy to > remember just for the sake of it, when the hierarchy present in the docs > (the view) is the one I'm likely to know by heart. > > So I'm not sure I'd like to just dump a chunk somewhere if it is not in > the code, as I wouldn't get into the right "mood" by just dumping a > fragment somewhere (how do I find the fragment again later? At least > with the codebase I'd know where to look.) So I think I'm not a big > supporter of MVC with chunks as seperate files in a seperate directory. > > However, if all I have to do is submit trac tickets containing > documentation for a feature I just wrote, then I don't care much either way. > > Dag Sverre > _______________________________________________ > Cython-dev mailing list > [email protected] > http://codespeak.net/mailman/listinfo/cython-dev >
The thing that's different about Cython from the others, is that it's not a library which is API centric.. where extracting doc strings from the code source itself makes perfect sense. But, I don't feel that it's necessarily impractical in Cython's case either. It all depends on preference, I think. _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
