Documentation build with waf

[Andrew Bartlett]

On Sat, 2013-05-18 at 10:30 +0200, Luk Claes wrote:
> Hi Andrew
> 
> On 05/17/2013 11:56 PM, Andrew Bartlett wrote:
> > On Fri, 2013-05-17 at 15:19 +0200, Luk Claes wrote:
> 
> > I'm curious, what made you want to build just the documentation?  (that
> > said, I think metze got you some patches for that)
> 
> 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. 

> >> This would require new documentation targets in the waf build if I'm not
> >> mistaken? It would also mean that not only manpages, but also html would
> >> be created in the waf build. How can one do that?
> > 
> > We didn't add an waf build for the non-manpage documentation because
> > this is no longer in a releasable state.  Indeed, we almost decided to
> > drop it entirely!
> 
> 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?

> >> 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?
> 
> >> 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.

Andrew Bartlett

-- 
Andrew Bartlett                                http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org