Ticket #2380: build-docs-2380.patch

File build-docs-2380.patch, 5.7 KB (added by thijs, 5 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:])