source: rtems-docs/common/waf.py @ 8b67c91

5
Last change on this file since 8b67c91 was 21c1a44, checked in by Chris Johns <chrisj@…>, on 11/02/18 at 03:05:51

waf: Add support to build PlantUML and Ditaa images.
  • Property mode set to 100644
File size: 19.1 KB
Line 
1#
2# RTEMS Documentation Project
3#
4# Waf build support.
5#
6
7
8from __future__ import print_function
9
10import os
11import re
12import sys
13
14from waflib.Build import BuildContext
15
16import latex
17
18sphinx_min_version = (1, 3)
19
20def build_date():
21    import datetime
22    now = datetime.date.today()
23    m = now.strftime('%B')
24    y = now.strftime('%Y')
25    if now.day % 10 == 1:
26        s = 'st'
27    elif now.day % 10 == 2:
28        s = 'nd'
29    elif now.day == 3:
30        s = 'rd'
31    else:
32        s = 'th'
33    d = '%2d%s' % (now.day, s)
34    return '%s %s %s' % (d, m, y)
35
36def version_cmdline(ctx):
37    return '-Drelease="%s" -Dversion="%s"' % (ctx.env.VERSION, ctx.env.VERSION)
38
39def sphinx_cmdline(ctx, build_type, conf_dir, doctrees,
40                   source_dir, output_dir, configs = []):
41    cfgs = ''
42    for c in configs:
43        cfgs += ' -D %s=%s' % (c, configs[c])
44    rule = "${BIN_SPHINX_BUILD} %s -b %s -c %s %s -d %s %s %s %s ${SRC}" % \
45           (sphinx_verbose(ctx), build_type, conf_dir, version_cmdline(ctx),
46            doctrees, cfgs, source_dir, output_dir)
47    return rule
48
49def cmd_spell(ctx):
50    from waflib import Options
51    from sys import argv
52    from subprocess import call
53
54    Options.commands = None # stop warnings about knowing commands.
55
56    if not ctx.env.BIN_ASPELL:
57        ctx.fatal("'aspell' is required please install and re-run configure.")
58
59    if len(argv) < 3:
60        ctx.fatal("Please supply at least one file name")
61
62    files = argv[2:]
63
64    path = ctx.path.parent.abspath()
65
66    # XXX: add error checking eg check if file exists.
67    for file in files:
68        cmd = ctx.env.BIN_ASPELL + \
69              ["-c",
70               "--personal=%s/common/spell/dict/rtems" % path,
71               "--extra-dicts=%s/common/spell/en_GB-ise-w_accents.multi" % path,
72               file]
73        print("running:", cmd)
74        call(cmd)
75
76def cmd_linkcheck(ctx):
77    conf_dir = ctx.path.get_src()
78    source_dir = ctx.path.get_src()
79    buildtype = 'linkcheck'
80    build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype)
81    rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir)
82    ctx(
83        rule   = rule,
84        cwd    = ctx.path.abspath(),
85        source = ctx.path.ant_glob('**/*.rst'),
86        target = "linkcheck/output.txt"
87    )
88
89class spell(BuildContext):
90    __doc__ = "Check spelling.  Supply a list of files or a glob (*.rst)"
91    cmd = 'spell'
92    fun = 'cmd_spell'
93
94class linkcheck(BuildContext):
95    __doc__ = "Check all external URL references."
96    cmd = 'linkcheck'
97    fun = 'cmd_linkcheck'
98
99def check_sphinx_version(ctx, minver):
100    try:
101        import sphinx
102        # sphinx.version_info was introduced in sphinx ver 1.2
103        version = sphinx.version_info
104        # version looks like (1, 7, 0, 'final', 0))
105        ver = version[0:2]
106    except:
107        try:
108            # sphinx-build returns its version info in stderr
109            (out, err) = ctx.cmd_and_log(ctx.env.BIN_SPHINX_BUILD +
110                              ['--version'], output=Context.BOTH)
111            # err looks like 'sphinx-build 1.7.0\n'
112            version = err.split(" ")[-1:][0].strip()
113            ver = tuple(map(int, re.split('[\D]', version)))
114        except:
115            try:
116                # sphinx-build returns its version info in stdout
117                version = ctx.cmd_and_log(ctx.env.BIN_SPHINX_BUILD +
118                              ['--version']).split(" ")[-1:][0].strip()
119                try:
120                    ver = tuple(map(int, re.split('[\D]', version)))
121                except:
122                    ctx.fatal("Sphinx version cannot be checked")
123            except:
124                ctx.fatal("Sphinx version cannot be checked: %s" % version)
125    if ver < minver:
126        ctx.fatal("Sphinx version is too old: %s" % ".".join(map(str, ver)))
127    return ver
128
129def sphinx_verbose(ctx):
130    return ' '.join(ctx.env.SPHINX_VERBOSE)
131
132def is_top_build(ctx):
133    from_top = False
134    if ctx.env['BUILD_FROM_TOP'] and ctx.env['BUILD_FROM_TOP'] == 'yes':
135        from_top = True
136    return from_top
137
138def build_dir_setup(ctx, buildtype):
139    where = buildtype
140    if is_top_build(ctx):
141        where = os.path.join(ctx.path.name, where)
142    bnode = ctx.bldnode.find_node(where)
143    if bnode is None:
144        ctx.bldnode.make_node(where).mkdir()
145    build_dir = ctx.path.get_bld().relpath()
146    output_node = ctx.path.get_bld().make_node(buildtype)
147    output_dir = output_node.abspath()
148    doctrees = os.path.join(os.path.dirname(output_dir), 'doctrees', buildtype)
149    return build_dir, output_node, output_dir, doctrees
150
151def pdf_resources(ctx, buildtype):
152    packages_base = ctx.path.parent.find_dir('common/latex')
153    if packages_base is None:
154        ctx.fatal('Latex package directory not found')
155    base = packages_base.path_from(ctx.path)
156    fnode = ctx.path.get_bld().make_node(buildtype)
157    fnode.mkdir()
158    local_packages = latex.local_packages()
159    targets = []
160    if local_packages is not None:
161        srcs = [os.path.join(base, p) for p in local_packages]
162        targets += [fnode.make_node(p) for p in local_packages]
163        ctx(features = "subst",
164            is_copy  = True,
165            source   = srcs,
166            target   = targets)
167    targets += [fnode.make_node('rtemsextrafonts.sty')]
168    ctx(features = "subst",
169        is_copy  = True,
170        source   = os.path.join(base, ctx.env.RTEMSEXTRAFONTS),
171        target   = fnode.make_node('rtemsextrafonts.sty'))
172    return targets
173
174def html_resources(ctx, buildtype):
175    extra_source = []
176    for dir_name in ["_static", "_templates"]:
177        files = ctx.path.parent.find_node("common").ant_glob("%s/*" % dir_name)
178        fnode = ctx.path.get_bld().make_node(os.path.join(buildtype, dir_name))
179        targets = [fnode.make_node(x.name) for x in files]
180        extra_source += targets
181        fnode.mkdir() # dirs
182        ctx(features = "subst",
183            is_copy  = True,
184            source   = files,
185            target   = targets)
186        ctx.add_group()
187    return extra_source
188
189def check_sphinx_extension(ctx, extension):
190    def run_sphinx(bld):
191        rst_node = bld.srcnode.make_node('testbuild/contents.rst')
192        rst_node.parent.mkdir()
193        rst_node.write('.. COMMENT test sphinx\n')
194        bld(rule = bld.kw['rule'], source = rst_node)
195
196    ctx.start_msg("Checking for '%s'" % (extension))
197    try:
198        ctx.run_build(fragment = 'xx',
199                      rule = "${BIN_SPHINX_BUILD} -b html -D extensions=%s -C . out" % (extension),
200                      build_fun = run_sphinx,
201                      env = ctx.env)
202    except ctx.errors.ConfigurationError:
203        ctx.end_msg('not found (see README.txt)', 'RED')
204        ctx.fatal('The configuration failed')
205    ctx.end_msg('found')
206
207def cmd_configure(ctx):
208    check_sphinx = not ctx.env.BIN_SPHINX_BUILD
209    if check_sphinx:
210        ctx.msg('Checking version', ctx.env.VERSION)
211
212        ctx.find_program("sphinx-build", var="BIN_SPHINX_BUILD", mandatory = True)
213        ctx.find_program("aspell", var = "BIN_ASPELL", mandatory = False)
214
215        ctx.start_msg("Checking if Sphinx is at least %s.%s" % sphinx_min_version)
216        ver = check_sphinx_version(ctx, sphinx_min_version)
217        ctx.end_msg("yes (%s)" % ".".join(map(str, ver)))
218
219        ctx.start_msg("Checking Sphinx Verbose ")
220        if 'SPHINX_VERBOSE' not in ctx.env:
221            ctx.env.append_value('SPHINX_VERBOSE', ctx.options.sphinx_verbose)
222            level = sphinx_verbose(ctx)
223            if level == '-Q':
224                level = 'quiet'
225            ctx.end_msg(level)
226        #
227        # Check extensions.
228        #
229        check_sphinx_extension(ctx, 'sphinx.ext.autodoc')
230        check_sphinx_extension(ctx, 'sphinx.ext.coverage')
231        check_sphinx_extension(ctx, 'sphinx.ext.doctest')
232        check_sphinx_extension(ctx, 'sphinx.ext.graphviz')
233        check_sphinx_extension(ctx, 'sphinx.ext.intersphinx')
234        check_sphinx_extension(ctx, 'sphinx.ext.mathjax')
235        check_sphinx_extension(ctx, 'sphinxcontrib.bibtex')
236
237    #
238    # Optional builds.
239    #
240    ctx.env.BUILD_PDF = 'no'
241    if ctx.options.pdf:
242        check_tex = not ctx.env.PDFLATEX
243        if check_tex:
244            ctx.load('tex')
245            if not ctx.env.PDFLATEX or not ctx.env.MAKEINDEX:
246                ctx.fatal('The programs pdflatex and makeindex are required for PDF output')
247            if 'PDFLATEXFLAGS' not in ctx.env or \
248               '-shell-escape' not in ctx.env['PDFLATEXFLAGS']:
249                ctx.env.append_value('PDFLATEXFLAGS', '-shell-escape')
250            latex.configure_tests(ctx)
251        ctx.env.BUILD_PDF = 'yes'
252
253    ctx.envBUILD_SINGLEHTML = 'no'
254    if ctx.options.singlehtml:
255        check_inliner = not ctx.env.BIN_INLINER
256        if check_inliner:
257            ctx.env.BUILD_SINGLEHTML = 'yes'
258            ctx.find_program("inliner", var = "BIN_INLINER", mandatory = False)
259            if not ctx.env.BIN_INLINER:
260                ctx.fatal("Node.js inliner is required install with 'npm install -g inliner' " +
261                          "(https://github.com/remy/inliner)")
262
263    ctx.envBUILD_PLANTUML = 'no'
264    if ctx.options.plantuml:
265        check_plantuml = not ctx.env.BIN_PUML
266        if check_plantuml:
267            ctx.env.BUILD_PLANTUML = 'yes'
268            ctx.find_program("puml", var = "BIN_PUML", mandatory = False)
269            if not ctx.env.BIN_PUML:
270                ctx.fatal("Node.js puml is required install with 'npm install -g node-plantuml' " +
271                          "(https://www.npmjs.com/package/node-plantuml)")
272
273    ctx.envBUILD_DITAA = 'no'
274    if ctx.options.ditaa:
275        #
276        # We use DITAA via PlantUML
277        #
278        if not ctx.env.BIN_PUML:
279            ctx.find_program("puml", var = "BIN_PUML", mandatory = False)
280            if not ctx.env.BIN_PUML:
281                ctx.fatal("DITAA uses PlantUML; " +
282                          "Node.js puml is required install with 'npm install -g node-plantuml' " +
283                          "(https://www.npmjs.com/package/node-plantuml)")
284        check_ditaa = not ctx.env.BIN_DITAA
285        if check_ditaa:
286            ctx.env.BUILD_DITAA = 'yes'
287            ctx.find_program("ditaa", var = "BIN_DITAA", mandatory = False)
288            if not ctx.env.BIN_DITAA:
289                ctx.fatal("DITAA not found, plase install")
290
291def doc_pdf(ctx, source_dir, conf_dir, extra_source):
292    buildtype = 'latex'
293    build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype)
294    resources = pdf_resources(ctx, buildtype)
295    rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir)
296    ctx(
297        rule         = rule,
298        cwd          = ctx.path,
299        source       = ctx.path.ant_glob('**/*.rst') + extra_source,
300        depends_on   = extra_source,
301        target       = ctx.path.find_or_declare("%s/%s.tex" % (buildtype,
302                                                               ctx.path.name))
303    )
304    ctx(
305        features     = 'tex',
306        cwd          = output_dir,
307        type         = 'pdflatex',
308        source       = "%s/%s.tex" % (buildtype, ctx.path.name),
309        prompt       = 0
310    )
311    ctx.install_files('${PREFIX}',
312                      '%s/%s.pdf' % (buildtype, ctx.path.name),
313                      cwd = output_node,
314                      quiet = True)
315
316def doc_singlehtml(ctx, source_dir, conf_dir, extra_source):
317    #
318    # Use a run command to handle stdout and stderr output from inliner. Using
319    # a standard rule in the build context locks up.
320    #
321    def run(task):
322        src = task.inputs[0].abspath()
323        tgt = task.outputs[0].abspath()
324        cmd = '%s %s' % (task.env.BIN_INLINER[0], src)
325        so = open(tgt, 'w')
326        se = open(tgt + '.err', 'w')
327        r = task.exec_command(cmd, stdout = so, stderr = se)
328        so.close()
329        se.close()
330        #
331        # The inliner does not handle internal href's correctly and places the
332        # input's file name in the href. Strip these.
333        #
334        with open(tgt, 'r') as i:
335            before = i.read()
336            after = before.replace('index.html', '')
337        i.close()
338        with open(tgt, 'w') as o:
339            o.write(after)
340        o.close()
341        return r
342
343    buildtype = 'singlehtml'
344    build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype)
345    resources = html_resources(ctx, buildtype)
346    rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir)
347    ctx(
348        rule         = rule,
349        cwd          = ctx.path,
350        source       = ctx.path.ant_glob('**/*.rst') + extra_source,
351        depends_on   = resources,
352        target       = ctx.path.find_or_declare("%s/index.html" % (buildtype)),
353        install_path = None
354    )
355    ctx(
356        rule         = run,
357        inliner      = ctx.env.BIN_INLINER,
358        source       = "%s/index.html" % buildtype,
359        target       = "%s/%s.html" % (buildtype, ctx.path.name),
360        install_path = '${PREFIX}'
361    )
362
363def doc_html(ctx, source_dir, conf_dir, extra_source):
364    buildtype = 'html'
365    build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype)
366    resources = html_resources(ctx, buildtype)
367    templates = os.path.join(str(ctx.path.get_bld()), buildtype, '_templates')
368    configs = { 'templates_path': templates }
369    rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir, configs)
370    ctx(
371        rule         = rule,
372        cwd          = ctx.path,
373        source       = ctx.path.ant_glob('**/*.rst') + extra_source,
374        depends_on   = resources,
375        target       = ctx.path.find_or_declare('%s/index.html' % buildtype),
376        install_path = None
377    )
378    ctx.install_files('${PREFIX}/%s' % (ctx.path.name),
379                      output_node.ant_glob('**/*', quiet = True),
380                      cwd = output_node,
381                      relative_trick = True,
382                      quiet = True)
383
384def images_plantuml(ctx, source_dir, conf_dir, ext):
385    #
386    # Use a run command to handle stdout and stderr output from puml.
387    #
388    def run(task):
389        src = task.inputs[0].abspath()
390        tgt = task.outputs[0].abspath()
391        cmd = '%s generate %s -o %s' % (task.env.BIN_PUML[0], src, tgt)
392        so = open(tgt + '.out', 'w')
393        r = task.exec_command(cmd, stdout = so, stderr = so)
394        so.close()
395        return r
396
397    for src in ctx.path.ant_glob('**/*' + ext):
398        tgt = src.abspath()[: - len(ext)] + '.png'
399        ctx(
400            rule         = run,
401            inliner      = ctx.env.BIN_PUML,
402            source       = src,
403            target       = tgt,
404            install_path = None
405    )
406
407
408def cmd_build(ctx, extra_source = []):
409    conf_dir = ctx.path.get_src()
410    source_dir = ctx.path.get_src()
411
412    if ctx.env.BUILD_PDF == 'yes':
413        doc_pdf(ctx, source_dir, conf_dir, extra_source)
414
415    if ctx.env.BUILD_SINGLEHTML == 'yes':
416        doc_singlehtml(ctx, source_dir, conf_dir, extra_source)
417
418    doc_html(ctx, source_dir, conf_dir, extra_source)
419
420def cmd_build_images(ctx):
421    conf_dir = ctx.path.get_src()
422    source_dir = ctx.path.get_src()
423    if ctx.env.BUILD_PLANTUML == 'yes':
424        images_plantuml(ctx, source_dir, conf_dir, '.puml')
425    if ctx.env.BUILD_DITAA == 'yes':
426        images_plantuml(ctx, source_dir, conf_dir, '.ditaa')
427
428def cmd_options(ctx):
429    ctx.add_option('--disable-extra-fonts',
430                   action = 'store_true',
431                   default = False,
432                   help = "Disable building with extra fonts for better quality (lower quality).")
433    ctx.add_option('--sphinx-verbose',
434                   action = 'store',
435                   default = "-Q",
436                   help = "Sphinx verbose.")
437    ctx.add_option('--pdf',
438                   action = 'store_true',
439                   default = False,
440                   help = "Build PDF.")
441    ctx.add_option('--singlehtml',
442                   action = 'store_true',
443                   default = False,
444                   help = "Build Single HTML file, requires Node Inliner")
445    ctx.add_option('--plantuml',
446                   action = 'store_true',
447                   default = False,
448                   help = "Build PlantUML images from source, need puml from npm")
449    ctx.add_option('--ditaa',
450                   action = 'store_true',
451                   default = False,
452                   help = "Build DITAA images using PlantUML from source, need ditaa and puml")
453
454def cmd_options_path(ctx):
455    cmd_options(ctx)
456    ctx.add_option('--rtems-path-py',
457                   type = 'string',
458                   help = "Full path to py/ in RTEMS source repository.")
459
460def cmd_configure_path(ctx):
461    if not ctx.options.rtems_path_py:
462        ctx.fatal("--rtems-path-py is required")
463
464    ctx.env.RTEMS_PATH = ctx.options.rtems_path_py
465
466    cmd_configure(ctx)
467
468def xml_catalogue(ctx, building):
469    #
470    # The following is a hack to find the top_dir because the task does
471    # provided a reference to top_dir like a build context.
472    #
473    top_dir = ctx.get_cwd().find_node('..')
474    #
475    # Read the conf.py files in each directory to gather the doc details.
476    #
477    catalogue = {}
478    sp = sys.path[:]
479    for doc in building:
480        #
481        # Import using the imp API so the module is reloaded for us.
482        #
483        import imp
484        sys.path = [top_dir.find_node(doc).abspath()]
485        mf = imp.find_module('conf')
486        sys.path = sp[:]
487        try:
488            bconf = imp.load_module('bconf', mf[0], mf[1], mf[2])
489        finally:
490            mf[0].close()
491        catalogue[doc] = {
492            'title': bconf.project,
493            'version': str(ctx.env.VERSION),
494            'release': str(ctx.env.VERSION),
495            'pdf': bconf.latex_documents[0][1].replace('.tex', '.pdf'),
496            'html': '%s/index.html' % (doc),
497            'singlehtml': '%s.html' % (doc)
498        }
499        bconf = None
500
501    import xml.dom.minidom as xml
502    cat = xml.Document()
503
504    root = cat.createElement('rtems-docs')
505    root.setAttribute('date', build_date())
506    cat.appendChild(root)
507
508    heading = cat.createElement('catalogue')
509    text = cat.createTextNode(str(ctx.env.VERSION))
510    heading.appendChild(text)
511    root.appendChild(heading)
512
513    builds = ['html']
514    if ctx.env.BUILD_PDF == 'yes':
515        builds += ['pdf']
516    if ctx.env.BUILD_SINGLEHTML == 'yes':
517        builds += ['singlehtml']
518
519    for d in building:
520        doc = cat.createElement('doc')
521        name = cat.createElement('name')
522        text = cat.createTextNode(d)
523        name.appendChild(text)
524        title = cat.createElement('title')
525        text = cat.createTextNode(catalogue[d]['title'])
526        title.appendChild(text)
527        release = cat.createElement('release')
528        text = cat.createTextNode(catalogue[d]['release'])
529        release.appendChild(text)
530        version = cat.createElement('version')
531        text = cat.createTextNode(catalogue[d]['version'])
532        version.appendChild(text)
533        doc.appendChild(name)
534        doc.appendChild(title)
535        doc.appendChild(release)
536        doc.appendChild(version)
537        for b in builds:
538            output = cat.createElement(b)
539            text = cat.createTextNode(catalogue[d][b])
540            output.appendChild(text)
541            doc.appendChild(output)
542        root.appendChild(doc)
543
544    catnode = ctx.get_cwd().make_node('catalogue.xml')
545    catnode.write(cat.toprettyxml(indent = ' ' * 2, newl = os.linesep))
546
547    cat.unlink()
Note: See TracBrowser for help on using the repository browser.