Opened 10 years ago

Closed 4 years ago

#2380 task closed fixed (fixed)

Make it possible to update the website with new documentation

Reported by: Jean-Paul Calderone Owned by: therve
Priority: normal Milestone: totally automated release infrastructure
Component: release management Keywords:
Cc: Jean-Paul Calderone Branch: branches/build-docs-2380-2
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs, therve

Description

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.

Attachments (1)

build-docs-2380.patch (5.7 KB) - added by Thijs Triemstra 5 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 7 years ago by Jean-Paul Calderone

#4355 was a duplicate of this.

comment:2 Changed 7 years ago by Jean-Paul Calderone

Component: corerelease management

comment:3 Changed 6 years ago by <automation>

Owner: radix deleted

Changed 5 years ago by Thijs Triemstra

Attachment: build-docs-2380.patch added

comment:4 Changed 5 years ago by Thijs Triemstra

Milestone: regular-releases
Owner: set to Thijs Triemstra
Status: newassigned

comment:5 Changed 5 years ago by Thijs Triemstra

Author: thijs
Branch: branches/build-docs-2380

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

comment:6 Changed 5 years ago by Thijs Triemstra

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

comment:7 Changed 5 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

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

comment:8 Changed 5 years ago by Jonathan Jacobs

Keywords: review removed
Owner: set to Thijs Triemstra

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.

comment:9 Changed 4 years ago by therve

Author: thijsthijs, therve
Branch: branches/build-docs-2380branches/build-docs-2380-2

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

comment:10 Changed 4 years ago by therve

Keywords: review added
Owner: Thijs Triemstra deleted

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

comment:11 Changed 4 years ago by Jonathan Jacobs

Keywords: review removed
Owner: set to therve

Thanks for coming back to this!

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

comment:12 Changed 4 years ago by therve

Resolution: fixed
Status: newclosed

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

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

Add a script to build documentation for the release.

Note: See TracTickets for help on using tickets.