From: Ian B. <ia...@co...> - 2003-01-20 08:33:51
|
On Mon, 2003-01-20 at 00:46, Stuart Donaldson wrote: > I am a little uncomfortable with the fact that I couldn't duplicate your > HTML from the released docutils, but had to resort to the current snapshot. I think the docutils release is a bit out of date at this point -- there's been a lot of work done since that release from what I can tell. There's even new directives that I want to use that weren't there when I first wrote the Webware documents. I'm going to keep using CVS for the foreseeable future, because I'm doing some work with it in the hopes of automating more of our documentation (at least that's what I've been doing today, and progress has been quite good). Since I'd like to contribute that back to the docutils project I need to stay in sync. > I recommend that we either use the standard release, incorporate the > snapshot we're going to use into our CVS tree much like what appears to > have been done with the DocSupport module in Webware right now. We could put a snapshot in our downloads, but docutils is too big to put into the Webware tree. If it was a couple modules that would be fine, but it's like a third of the size of Webware which is a bit too large. > I also find that since docutils/tools/buildhtml.py isn't installed as a > part of the installation process of docutils, it makes it more difficult > to automate its use. (Although if we incorporated a snapshot like we do > with DocSupport, that could solve this problem.) Yeah, it's a bit of installation. I'd also like to make a script to both build the documentation and upload it to the website in one command. And I'd like to make buildhtml.py (or another script) a bit smarter. But even if people can't generate the documents, they can still work with the text files and participate in that way. If they are serious about working on the documentation it's not that hard to install docutils and use the tools. I will document the process in Development.txt at some point. > Other than that, I agree that the text files are easier to work in. > > I am not sure we need to split off the documentation in CVS. However it > might make sense to have a sourceforge package for Webware-docs similar > to the Webware-devel package I created for the releases. This would > allow publishing of documentation packages on an independent schedule > from publishing Webware releases. This is an internet world... do we need to release a downloadable package like that? Can't we just put it on our website? Well, it's useful to be able to download it all at once for offline viewing or whatnot, but I don't think we need to go through formal releases. Snapshots should be completely sufficient, IMHO. Except for documentation that's more intimately tied to a release, like reference documentation -- but that documentation should be in the release anyway. -- Ian Bicking Colorstudy Web Development ia...@co... http://www.colorstudy.com PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7 4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241 |