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
