Make it possible to update the website with new documentation

[exarkun]

The lore-processed howto documentation is presented on the website. Updating this documentation is extremely time consuming.

The release process and the website should be organized such that there is a simple command which will cause the new documentation to appear on the website.

[exarkun]

#4355 was a duplicate of this.

[thijs]

(In [33530]) Branching to 'build-docs-2380'

[thijs]

(In [33535]) add build-docs script, refs #2380

[thijs]

I copied the temporary script on [ReleaseProcess#Buildhowtodocumentsforwebsite] and hooked it up to a build-docs script.

$ bin/admin/build-docs
Must specify three arguments: Twisted checkout path, destination path, and template path.
$ bin/admin/build-docs . ./book ../../../../../twisted-website/docs/website-template.tpl 
pnmtops: writing color PostScript...
pnmtops: writing color PostScript...
pnmtops: writing color PostScript...
pnmtops: writing color PostScript...
pnmtops: writing color PostScript...
pnmtops: writing color PostScript...
pnmtops: warning, image too large for page, rescaling to 0.93578
pnmtops: writing color PostScript...
ls -lh book/
total 1.4M
-rwxrwxr-x 1 thijs thijs 1.4M 2012-02-10 18:14 book.pdf

[jonathanj]

Thanks for doing this.

My main concern here is the lack of test coverage for the behaviour of BuildDocsScript.buildDocs. I think breaking buildDocs into its smaller components and parameterizing the builder type would make the code both easier to test and read.

[therve]

(In [37718]) Branching to 'build-docs-2380-2'

[therve]

Alright, there is one test now, plus a couple of other fixes. Please review!

[jonathanj]

Thanks for coming back to this!

I think the only item is that setupTeXFiles, _setupTeXSections and _setupTeXBook need docstrings.

[therve]

(In [37746]) Merge build-docs-2380-2

Authors: thijs, therve Reviewer: jonathanj Fixes: #2380

Add a script to build documentation for the release.