On Fri, Oct 2, 2009 at 5:25 AM, Peter Alexander <[email protected]> wrote: > 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. >
More... come to think of it.. all of Qt's documenation (including technology elaborations, exaples and demos) reside within the source code itself. They use "qdoc" to extract it to a view. This is what DOxygen is modelled after which all though is primarily for API extraction, is not solely for that purpose either. _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
