'Main build method.  First updates the environment, and then
calls :meth:`write`.'

def build(self, docnames, summary=None, method='update'):

    if summary:
        self.info(bold(('building    [%s]:    ' % self.name)), nonl=1)
        self.info(summary)
    updated_docnames = set()
    warnings = []
    self.env.set_warnfunc((lambda *args: warnings.append(args)))
    self.info(bold('updating    environment:    '), nonl=1)
    (msg, length, iterator) = self.env.update(self.config, self.srcdir, self.doctreedir, self.app)
    self.info(msg)
    for docname in self.status_iterator(iterator, 'reading    sources...    ', purple, length):
        updated_docnames.add(docname)
    for warning in warnings:
        self.warn(*warning)
    self.env.set_warnfunc(self.warn)
    doccount = len(updated_docnames)
    self.info(bold('looking    for    now-outdated    files...    '), nonl=1)
    for docname in self.env.check_dependents(updated_docnames):
        updated_docnames.add(docname)
    outdated = (len(updated_docnames) - doccount)
    if outdated:
        self.info(('%d    found' % outdated))
    else:
        self.info('none    found')
    if updated_docnames:
        self.info(bold('pickling    environment...    '), nonl=True)
        self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME))
        self.info('done')
        self.info(bold('checking    consistency...    '), nonl=True)
        self.env.check_consistency()
        self.info('done')
    elif ((method == 'update') and (not docnames)):
        self.info(bold('no    targets    are    out    of    date.'))
        return
    self.write(docnames, list(updated_docnames), method)
    self.finish()
    status = (((self.app.statuscode == 0) and 'succeeded') or 'finished    with    problems')
    if self.app._warncount:
        self.info(bold(('build    %s,    %s    warning%s.' % (status, self.app._warncount, (((self.app._warncount != 1) and 's') or '')))))
    else:
        self.info(bold(('build    %s.' % status)))
