On Thu, 2010-02-11 at 15:31 +0100, Andreas Jellinghaus wrote: > Hi, > > we generate some docs with doxygen, others with a shell > script using wget and xslt to download our wiki and > create local html files from that). > > that mechanism is currently enabled with "--enable-doc", > off by default as it is time-consuming and usualy not > wanted. > > the problem I have is this: > * I want people to checkout svn and compile and test the > software without generating documentation. > * if people want the docs, they should be able to create > them too. > * if I run "make distcheck", I want the existing documentation > to be included in the tar.gz file. > * if I run "make maintainer-clean", I want generate documentation > to be removed, so I can diff between a modified checkout and > an unmodified svn checkout. > > but our code to do all that is really ugly. so I wonder what the > best way to implement something like this is. can you give me an > advice? > > from my point of view documentation is on the same level as > "configure" and "makefile.in" - something we don't keep in > svn, but generate as first step after the checkout and > then distribute as part of the tar.gz to users. is there > some hook I can use to run custom commands easily from > autoconf/make/libtool? maybe even in a way I can turn > it on? (thus generate documentation only if asked) > > any better idea? thanks for your help. >
We have the same challenge at X.Org. Documents from various sources are generated using tools such as doxygen, asciidoc, xmlto, groff, and ps2pdf. I can state some reasons why generated docs and included in the tarball: 1) convenience 2) the target platform building the tarball does not have the tool 3) the target platform building the tarball has the tool, but at the wrong version In addition, we must prevent a platform that does not have the doc tool to be able to "create" a tarball for distribution with missing generated documentation. This is accomplished by having 'make dist' fail while 'make all' and 'make install' works. You have stated the requirements very well, and I meant to ask the same question a little while ago. I can share how I do it in the makefile if it can help. 1) an AM_CONDITIONAL --enable-doc which defines ENABLE_DOC : this allows the builder to include the docs or not, for whatever reason. 2) an AM_CONDITIONAL --with-doxygen which defines HAVE_DOXYGEN: the default behaviour is to skip the docs if the tool is missing. A builder can use --without-doxygen if the tool is at the wrong version or if it fails. This way other documentation can be build. 3) unconditionally add html generated files in EXTRA_DIST: this will cause 'make dist' to fail if the platform creating a tarball does not have the doc tool. 4) Add output message telling builder why 'make dist' fails when doc tool is missing 5) maintainer-clean-local: cleans the generated files. Uses the automake concept of "special tool" which the platform building the tarball may not have. This prevents removing generating docs with a regular make clean by accident. A makefile would like this: if ENABLE_DOC if HAVE_DOXYGEN doc target: @command maintainer-clean-local: @clean generated file else doc target: @echo Tell builder docs cannot be generated. Install the tool or use --with-doxygen endif else doc target: @echo Tell builder docs cannot be generated. Use --enable-doc endif EXTRA_DIST = all the html and doxygen files listed here I don't see a reason for the code to be ugly, in the sense that automake can be used as designed. It does increase the complexity and the requirements must be understood. I am setting aside any doxygen specific issues in that statement. We have written macros for the 2 conditionals in configure.ac as they are used in several packages. Regards, Gaetan > Regards, Andreas > p.s. if you want to see the code we currently have: > svn co http://www.opensc-project.org/svn/openct/trunk > and look at the docs/ directory. > >
signature.asc
Description: This is a digitally signed message part