On Thu, May 22, 2008 at 4:59 PM, Darren Dale <[EMAIL PROTECTED]> wrote: > I just committed the beginnings of a Sphinx-based documentation to svn. It > includes a section explaining how to get up and running with sphinx, its > *really easy*:
Darren, thanks a lot for getting this going. I think this is going to push the documentation effort forward significantly. It certainly has got me hot and bothered to write some docs! A couple of organizational things: - flat is better than nested. I think the basic organization is good but I want to balance the cleanliness of the developer/build view with the plain text user view. To that end, perhaps having a "source" subdir in doc/users_guide is overkill. Should we have all the *.txt file live next to the make.py file? I want users browsing the doc/users_guide dir to see all the stuff they need (artist tut, event handling tut, etc) withought getting confused by the "build" or "figures" or "data" subdirs living beside a "source" subdir). It seems that it would not significantly add to the clutter to have all the txt files at a higher level. We *could* go one step further, and have all the *.txt files live directly in the "doc" dir itself, and the various subdirs like "users_guide" or "api_reference" or "jpl" or whatever could reference the parent directory for the includes. I'm not sure this is right, but it is consistent with the view that we have a lot of modular, somewhat freestanding, human readable, plain text rest files that can be combined into whatever package one wants via include files (eg the JPL could make their own custom docs from the pool) and it would work like the (old) pylab examples dir (one stop shopping for examples with ls and grep). Admittedly, the examples organization eventually became unwieldy, which is why I reorganized it in the trunk, but that is a good problem to have and it took years to get there. Your call, but just some food for thought. - I think we should be mostly consistent with whether we use underscores to separate english words. So we have artist_api_tut .txt but userguide.txt. For the sake of a foolish consistency, how about user_guide.txt too? Great work! JDH ------------------------------------------------------------------------- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
