Documentation build with waf

[Luk Claes]

On 05/18/2013 10:41 AM, Andrew Bartlett wrote:
> On Sat, 2013-05-18 at 10:30 +0200, Luk Claes wrote:
>> On 05/17/2013 11:56 PM, Andrew Bartlett wrote:
>>> On Fri, 2013-05-17 at 15:19 +0200, Luk Claes wrote:
>> If one changes the documentation it's easier to test them when one is
>> able to regenerate just the documentation than to start a build of
>> everything.
> 
> Sure, but after you build everything once, it won't rebuild anything
> that hasn't changed after that. 

make clean in the docs-xml directory can take care of this.

>> Is there a reason the html is still in the release in that case?
> 
> I can't find any html files (other than SWAT) in our release, or
> generated and installed by our build process.  Can you clarify what you
> refer to here?

Oh, I did not have a look at what was specifically included. If it's
only SWAT documentation then it's fine as it is.

>>>> Another thing that would make maintaining the documentation easier is
>>>> not having to specify each individual manpage (or html) in the wscript
>>>> file. Is that possible?
>>
>> Did you skip this question by mistake?

Apparently not, can someone else answer this question?

>>>> A last request would be that one could require the build to fail when
>>>> the documentation is not build instead of silently not building the
>>>> documentation as now is the case. How can one reach that goal? Maybe
>>>> that's trivial when using separate targets?
>>>
>>> The issue is that this would require xlstproc and docbook-xsl on all
>>> hosts building from source, as the waf build doesn't use pre-built
>>> documentation in the tarballs.  Pre-built stuff doesn't work well with
>>> waf, as a general rule, but we can probably hack the install stage to at
>>> least install the manpages from docs/ in the tarball. 
>>
>> What's wrong with requiring xsltproc and docbook-xsl on a build host?
> 
> Samba's waf build tries to require as few tools as possible,
> essentially, cc, python, perl.  This is to allow Samba to build on as
> many different platforms as possible, such as ancient Unix.  It actually
> does that pretty well.

Ok. Would it be possible to make it configurable: if one really wants to
build the documentation the build fails when xsltproc or docbook-xsl are
not available?

Cheers

Luk