On Thursday 22 May 2008 10:10:13 pm John Hunter wrote: > 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.
I just removed the source directories, like you suggested. You might get errors the next time you run make.py, just delete the build directories and it should correct itself. > 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. This way could work, but I think it would quickly become unwieldy. Lets stick with this for now, we can always reorganize later if we feel strongly about it. This way, JPL or others can still reference docs in their sister directories. > - 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? This is improved in the trunk. Darren ------------------------------------------------------------------------- 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
