Ticket #2380: build-docs-2380.patch

File build-docs-2380.patch, 5.7 KB (added by thijs, 3 years ago)
  • twisted/python/_release.py

     
    424424    """ 
    425425    Generate API documentation from source files using 
    426426    U{pydoctor<http://codespeak.net/~mwh/pydoctor/>}.  This requires 
    427     pydoctor to be installed and usable (which means you won't be able to 
    428     use it with Python 2.3). 
     427    pydoctor to be installed and usable. 
    429428    """ 
    430429    def build(self, projectName, projectURL, sourceURL, packagePath, 
    431430              outputPath): 
     
    13671366            sys.exit("Must specify two arguments: " 
    13681367                     "Twisted checkout and destination path") 
    13691368        self.buildAPIDocs(FilePath(args[0]), FilePath(args[1])) 
     1369 
     1370 
     1371 
     1372class BuildDocsScript(object): 
     1373    """ 
     1374    A thing for building the main documentation. See L{main}. 
     1375    """ 
     1376 
     1377    def buildDocs(self, projectRoot, output, template): 
     1378        """ 
     1379        Build the main documentation of Twisted, with our project policy. 
     1380 
     1381        @param projectRoot: A L{FilePath} representing the root of the Twisted 
     1382            checkout. 
     1383        @type projectRoot: L{FilePath} 
     1384        @param output: A L{FilePath} pointing to the desired output directory. 
     1385        @type output: L{FilePath} 
     1386        @param template: A L{FilePath} pointing to the template file that is 
     1387            used for the look and feel of the howto documentation. 
     1388        @type template: L{FilePath} 
     1389        """ 
     1390        version = Project(projectRoot.child("twisted")).getVersion() 
     1391        versionString = version.base() 
     1392        apiURL = "http://twistedmatrix.com/documents/%s/api/" % versionString 
     1393        docRoot = projectRoot.child("doc") 
     1394        howtoRoot = docRoot.descendant(["core", "howto"]) 
     1395 
     1396        done = {} 
     1397        for p in docRoot.walk(): 
     1398            if p.basename() == 'man': 
     1399                done[p] = True 
     1400                ManBuilder().build(p) 
     1401 
     1402        for p in docRoot.walk(): 
     1403            if p.basename().endswith('.xhtml'): 
     1404                if p.parent() not in done: 
     1405                    done[p.parent()] = True 
     1406                    DocBuilder().build( 
     1407                        versionString, howtoRoot, p.parent(), 
     1408                        template, 
     1409                        apiURL + "%s.html", 
     1410                        False) 
     1411 
     1412        for p in done: 
     1413            print '     ', p.path 
     1414        BookBuilder().build(howtoRoot, done.keys(), 
     1415                            howtoRoot.child('book.tex'), 
     1416                            FilePath('book.pdf')) 
     1417 
     1418 
     1419    def main(self, args): 
     1420        """ 
     1421        Build the main documentation. 
     1422 
     1423        @type args: list of str 
     1424        @param args: The command line arguments to process.  This must contain 
     1425            three strings: the path to the root of the Twisted checkout, a path 
     1426            to an output directory, and the path to the Twisted website template. 
     1427        """ 
     1428        if len(args) != 3: 
     1429            sys.exit("Must specify three arguments: " 
     1430                     "Twisted checkout path, destination path, and template path.") 
     1431        self.buildDocs(FilePath(args[0]), FilePath(args[1]), FilePath(args[2])) 
  • twisted/python/test/test_release.py

     
    3535from twisted.python._release import NoDocumentsFound, filePathDelta 
    3636from twisted.python._release import CommandFailed, BookBuilder 
    3737from twisted.python._release import DistributionBuilder, APIBuilder 
    38 from twisted.python._release import BuildAPIDocsScript 
     38from twisted.python._release import BuildAPIDocsScript, BuildDocsScript 
    3939from twisted.python._release import buildAllTarballs, runCommand 
    4040from twisted.python._release import UncleanWorkingDirectory, NotWorkingDirectory 
    4141from twisted.python._release import ChangeVersionsScript, BuildTarballsScript 
     
    911911        self.assertEqual(linkrel, "../../howto/") 
    912912 
    913913 
     914    def test_docsBuilderScriptMainRequiresThreeArguments(self): 
     915        """ 
     916        SystemExit is raised when the incorrect number of command line 
     917        arguments are passed to the main documentation building script. 
     918        """ 
     919        script = BuildDocsScript() 
     920        self.assertRaises(SystemExit, script.main, []) 
     921        self.assertRaises(SystemExit, script.main, ["foo"]) 
     922        self.assertRaises(SystemExit, script.main, ["foo", "bar"]) 
     923        self.assertRaises(SystemExit, script.main, ["foo", "bar", "baz", "boo"]) 
     924 
     925 
     926    def test_docsBuilderScriptMain(self): 
     927        """ 
     928        The main documentation building script invokes the same code that 
     929        L{test_buildWithPolicy} tests. 
     930        """ 
     931        script = BuildDocsScript() 
     932        calls = [] 
     933        script.buildDocs = lambda a, b, c: calls.append((a, b, c)) 
     934        script.main(["hello", "hi", "there"]) 
     935        self.assertEqual(calls, [(FilePath("hello"), FilePath("hi"), 
     936            FilePath("there"))]) 
     937 
     938 
    914939 
    915940class APIBuilderTestCase(TestCase): 
    916941    """ 
  • bin/admin/build-docs

     
     1#!/usr/bin/env python 
     2 
     3# Copyright (c) Twisted Matrix Laboratories. 
     4# See LICENSE for details. 
     5 
     6# This script is not meant to be distributed to users of Twisted. 
     7# It is only for use in making upstream Twisted releases. 
     8 
     9import sys 
     10 
     11from twisted.python._release import BuildDocsScript 
     12 
     13BuildDocsScript().main(sys.argv[1:])