Opened 8 years ago

Closed 18 months ago

#2380 task closed fixed (fixed)

Make it possible to update the website with new documentation

Reported by: exarkun Owned by: therve
Priority: normal Milestone: totally automated release infrastructure
Component: release management Keywords:
Cc: exarkun Branch: branches/build-docs-2380-2
(diff, github, buildbot, log)
Author: thijs, therve Launchpad Bug:

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 3 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 4 years ago by exarkun

#4355 was a duplicate of this.

comment:2 Changed 4 years ago by exarkun

  • Component changed from core to release management

comment:3 Changed 4 years ago by <automation>

  • Owner radix deleted

Changed 3 years ago by thijs

comment:4 Changed 3 years ago by thijs

  • Milestone set to regular-releases
  • Owner set to thijs
  • Status changed from new to assigned

comment:5 Changed 3 years ago by thijs

  • Author set to thijs
  • Branch set to branches/build-docs-2380

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

comment:6 Changed 3 years ago by thijs

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

comment:7 Changed 3 years ago by thijs

  • Keywords review added
  • Owner thijs deleted
  • Status changed from assigned to new

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 3 years ago by jonathanj

  • Keywords review removed
  • Owner set to thijs

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 18 months ago by therve

  • Author changed from thijs to thijs, therve
  • Branch changed from branches/build-docs-2380 to branches/build-docs-2380-2

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

comment:10 Changed 18 months ago by therve

  • Keywords review added
  • Owner thijs deleted

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

comment:11 Changed 18 months ago by jonathanj

  • 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 18 months ago by therve

  • Resolution set to fixed
  • Status changed from new to closed

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