Jonathan Robie wrote:
I think we're converging on using svnpubsub to maintain documentation.
We need to determine our directory structure. Any of these structures
make sense to me. In all cases, qpid.apache.org includes Rajith's
index.html and associated .css, etc., as well as the DocBook generated
files. It would contain links to the download directory and the Wiki,
but not include them.
Here are some possible directory structures:
1. Make the web site a subdirectory of doc
doc/src <-- XML source files
doc/build <-- the build directory
doc/qpid.apache.org <-- the Apache web site, starting with index.html,
and including all documentation.
2. Make the web site a parallel directory to doc
qpd/cpp
qpid/doc
qpid/qpid.apache.org
I suppose it would also be logically possible to have the web site be on
a separate svn branch, or even in a separate svn repository.
I'm inclined to go with #2. Does anyone else have strong feelings on this?
I think the web site really needs to be a distinct repo from the one we
use for code for a few reasons.
First, it is very confusing and generally considered horribly bad
practice to mix source code and generated artifacts in the same repo.
This confuses build systems to no end since most build systems are
predicated upon the concept that they are the only thing that ever
modifies the output files. However if the output files are in svn, then
an svn update can cause an older file to appear newer than the input
resulting in very confusing and broken behavior where the build system
doesn't actually build everything that needs to be built. In this
circumstance this could very easily lead to a broken and partially
updated web site, especially when developers follow the best practice of
doing an svn update prior to building in order to ensure they are
working from fresh sources.
Secondly, I don't want to be exposed to getting multi-megabyte diffs
everytime someone updates the web site.
Thirdly, the doc source should be part of the source release (i.e. an
svn export), however the generated web site should *not*.
And finally, I think that if we're using svnpubsub for the web site, we
may well want to have other portions of the site in svn, not just the
docs, so the web site repo should be organized to reflect this.
--Rafael
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
