Vincent,
The project doxia-test-docs should contain the documents and the
document should be maintained in the projects source repository so
they can be release by the project, i.e. mvn release... The version
of this project should change whenever the source documents change,
i.e when you need to reload them from the "svn copy", and their is a
doxia release. The tests using doxia-test-docs may need to extract
the documents from the doxia-test-doc artifact/jar, for which their
are maven tools to do the unpacking.
Keep in mind, one of the reasons for Maven is enable any user at any
time the ability to successfully rebuild the project.
Paul Spencer
On Dec 10, 2008, at 8:19 PM, Vincent Siveton wrote:
Hi Benjamin and Paul,
According your comments, I created a new module doxia-test-docs which
includes svn copy on several documents. I also updated tests to fetch
these changes.
Any comments are welcome!
Cheers,
Vincent
2008/12/8 Benjamin Bentmann <[EMAIL PROTECTED]>:
Vincent Siveton wrote:
The tests are to perform XSD validations under our current
documentation. Since we add new XSD files in this release, I think
these tests are useful.
No doubt, tests are useful but I feel we mix two different test
targets
here:
a) correctness of the XSDs
b) correctness of the currently available Maven documentation
IMHO, only point a) should be a concern of Doxia, the rest is just
outside
world. The day we have a validating Doxia under the hood of the
Site Plugin
and it detects errors in our docs, we can simply fix them when be
try to
build the corresponding site, not when building Doxia.
Instead of svn co, we could link to relative doc path, ie from
doxia-module-fml using ../../../plugins/maven-ant-plugin/src/site
-1 on hard-coding inter-module or even worse inter-project paths.
This
introduces tight coupling where none should be. Imagine a
contributor to
Doxia who wants to try out patching it would end up checking out
Maven
plugins to test Doxia.
Also, both "svn co" and the relative path to a local checkout make
the idea
of a reproducible build unreachable, as Paul already pointed out.
To realize test target a), it is surely a nice idea to just grab
samples of
existing and presumable good docs and check whether the validator
doesn't
freak out. To do so, how about if we just collect all the doc files
of
interest from the Maven/plugin sites and copy them to a new Doxia
module
(doxia-test-docs or whatever). This module would mimic a "svn co"
of a
locked SVN revision and is also under Doxia control, i.e. one could
also
create artifical input documents to check more complex syntax
structures
that are currently not in use on the Maven sites. The other Doxia
modules
like XDoc etc. could depend on this test module and extract the
input files
from the test class path or from local file system after unpacking
with the
Dependency Plugin. Wouldn't that work?
Benjamin
