Documentation build with waf

[Karolin Seeger]

Hi,

On Sat, May 18, 2013 at 10:58:16AM +0200, Luk Claes wrote:
> 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.

I think that I mentioned that the html man pages need to be created by the
waf build, because I need them for the web site. When the docs-xml build
will be removed, I need to be able to build them with waf or we don't put
them on the web site any longer (but many people use it).
 
> >>>> 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,
Karo

-- 
Samba			http://www.samba.org
SerNet			http://www.sernet.de
sambaXP			http://www.sambaxp.org