couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@bytesexual.org>
Subject Re: Status Update
Date Sun, 30 Mar 2008 15:00:18 GMT
>> * I have updated all the source documentation to use Markdown following
>>   Chris's changes for the CouchDB incubation site.
>
> What source documentation is that?

AUTHORS, BUGS, DEVELOPMENT, NEWS, NOTICE, README, THANKS, TROUBLESHOOTING

>> * I have removed the generated HTML files from Subversion, this didn't seem
>>   like a good use of revision control.
>
> Oops, we'll have to revert that. From
> <http://incubator.apache.org/guides/sites.html>
>
> "Regardless of which tool you use, the web site should be maintained in the
> svn repository, and include the site generation tool as a binary file. This
> simplifies the process of site generation and enables changes to the site to
> be made by any committer. The generated site should also be checked into
> svn. This allows the generated site to be relocated to any part of the Apache
> site after incubation is complete."

I must profess that I can't follow the logic here. Why would keeping the files
out of Subversion prevent the site from being relocated?

Either way, I have reverted my change in revision 642749.

> For some reason these changes don't seem to have come through on
> couchdb-commits@ yet. I'm looking into them now.

Yes, neither has this thread appeared on the development list. Strange.

>> * I have added the /site/publish.sh script which can be run directly from a
>> source checkout on minotaur to build and publish the site.
>
> See above, this needs to be as simple (and was) as just an `svn up`.

As far as I can tell, the site is kept here:

  /www/incubator.apache.org/couchdb

Are you suggesting that this should be a Subversion checkout?

All my publish.sh script does in run ./build.sh and rsync the files in the local
directory tree to the above hard-coded path on the local filesystem.

> I don't think we should include the site in trunk, if only because of
> the requirement of keeping the generated files in the repository.

We could relocate the source files to /trunk/doc and provide a script which
could build the HTML in different places depending on invocation.

An example of how this might work:

  $ trunk/doc/build.sh      # builds into trunk/doc

  $ trunk/doc/build.sh site # builds into the site directory

This way, normal users can build the site and install it locally under
/usr/share/doc/html and we can build the site and keep it under /site as needed.

> Having generated HTML docs in tarballs is certainly a nice goal, but we
> should analyse what we'd like there and how to best achieve it.

As it stands, and as I see it, there is nothing on the website which wouldn't
also be appropriate to install on a local system.

As far as the devision of information, I can see the site evolving to include
the core/official documentation (like it has now) while the Wiki is more of a
collection of ideas/guides/thoughts/sketches etc. Again, this fits perfectly
with the idea of including the site as part of the tarball.

Thanks,

--
Noah Slater <http://bytesexual.org/>

Mime
View raw message