Re: advice for pre-generating documentation

[Gaetan Nadon]

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