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
