Ian Bicking wrote:
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 understand completely... Sounds deja-vu with my initial envolvement with Webware...  ;-)

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.
  
Agreed, the size is too big to incorporate into our tree.  A snapshot in downloads would suffice.

Something else to consider, is that install.py script could locate buildhtml.py, either on the path, or asking for it.  After finding, buildhtml.py (or not) it could create a command in our Webware/bin directory that would call the docutils buildhtml.py command. If the docutils version didn't exist, it could just display a reasonable message.

I am working on an update to ReleaseHelper.py to utilize "cvs export" rather than creating a copy of the current directory.  It would be good to have a standard command that could be invoked to build the html on anything that we want to be part of the release.  

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.
  
This may be a bit of a nit, but can you embed HTML comments in the output HTML files?  It would be a good idea if the HTML files contained a little better reference to their source and generation process than just the meta tag that docutils includes.  

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.
  
I'm fine with having it on the web site.  I'd like a downloadable link.  I don't see a requirement for a separate package, I was putting it forth as a suggestion.  I was more interested in pointing out that we don't need to split it off in CVS.  Just package up a release of the documentation seperately from a release of the product.  I would say having the documentation on the web site in a browsable form, is a must.  Having it there in a downloadable form is a very good idea.  Having the documentation as a package for downloading is a possible way to do the downloading.

-Stuart-