diff options
Diffstat (limited to 'doc/SConscript')
| -rw-r--r-- | doc/SConscript | 343 |
1 files changed, 241 insertions, 102 deletions
diff --git a/doc/SConscript b/doc/SConscript index 6b9d726..9c24aaa 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation +# Copyright (c) 2001 - 2014 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -42,6 +42,7 @@ fop = whereis('fop') xep = whereis('xep') epydoc_cli = whereis('epydoc') gs = whereis('gs') +lynx = whereis('lynx') # # @@ -96,6 +97,9 @@ if not fop and not xep: if skip_doc: print "doc: ...skipping building User Guide." else: + if not lynx: + print "doc: Warning, lynx is not installed...created release packages won't be complete!" + # # Always create a version.xml file containing the version information # for this run. Ignore it for dependency purposes so we don't @@ -104,7 +108,65 @@ else: date, ver, rev = env.Dictionary('DATE', 'VERSION', 'REVISION') version_xml = File(os.path.join(build, "version.xml")) writeVersionXml(str(version_xml), date, ver, rev) - + + import shutil + import SCons.Builder + import SCons.Util + # + # Builder for copying files to an Install dir, based + # on their extension (better: glob matching pattern)... + # + def _glob_install_action(target, source, env): + if not SCons.Util.is_List(target): + target = [target] + if not SCons.Util.is_List(source): + source = [source] + for t, s in zip(target, source): + shutil.copy(str(s), str(t)) + def _glob_install_emitter(target, source, env): + if not SCons.Util.is_List(target): + target = [target] + if not SCons.Util.is_List(source): + source = [source] + + res = [] + res_src = [] + tdir = env.Dir(target[0]) + for g in glob.glob(str(source[0])): + head, tail = os.path.split(g) + res.append(os.path.join(str(tdir), tail)) + res_src.append(g) + return res, res_src + _glob_install_builder = SCons.Builder.Builder(action=_glob_install_action, + emitter=_glob_install_emitter) + env['BUILDERS']['GlobInstall'] = _glob_install_builder + + # + # Builder for copying ChunkedHTML files to an Install dir... + # + def _chunked_install_action(target, source, env): + if not SCons.Util.is_List(target): + target = [target] + if not SCons.Util.is_List(source): + source = [source] + tdir, tail = os.path.split(str(target[0])) + spattern = os.path.join(os.path.split(str(source[0]))[0], '*.html') + for g in glob.glob(spattern): + shutil.copy(g, tdir) + + def _chunked_install_emitter(target, source, env): + if not SCons.Util.is_List(target): + target = [target] + if not SCons.Util.is_List(source): + source = [source] + + tdir = env.Dir(target[0]) + head, tail = os.path.split(str(source[0])) + return os.path.join(str(tdir), tail), source + _chunked_install_builder = SCons.Builder.Builder(action=_chunked_install_action, + emitter=_chunked_install_emitter) + env['BUILDERS']['ChunkedInstall'] = _chunked_install_builder + if not env.GetOption('clean'): # # Ensure that all XML files are valid against our XSD, and @@ -124,84 +186,94 @@ else: print "Not all example names and suffixes are unique! Please correct the errors listed above and try again." sys.exit(0) - # - # Copy generated files (.gen/.mod/.xml) to the build folder - # - env.Execute(Mkdir(os.path.join(build, 'generated'))) - env.Execute(Mkdir(os.path.join(build, 'generated', 'examples'))) - for g in glob.glob(os.path.join('generated', '*.gen')): - env.Execute(Copy(os.path.join(build, 'generated'), g)) - for g in glob.glob(os.path.join('generated', '*.mod')): - env.Execute(Copy(os.path.join(build, 'generated'), g)) - for g in glob.glob(os.path.join('generated', 'examples', '*')): - env.Execute(Copy(os.path.join(build, 'generated', 'examples'), g)) - - # - # Copy XSLT files (.xslt) to the build folder - # - env.Execute(Mkdir(os.path.join(build, 'xslt'))) - for g in glob.glob(os.path.join('xslt','*.*')): - env.Execute(Copy(os.path.join(build, 'xslt'), g)) - - # - # Copy Docbook stylesheets and Tool to the build folder - # - dbtoolpath = ['src', 'engine', 'SCons', 'Tool', 'docbook'] - env.Execute(Mkdir(os.path.join(build_dir, *dbtoolpath))) - env.Execute(Mkdir(os.path.join(build_dir, *(dbtoolpath + ['utils'])))) - env.Execute(Copy(os.path.join(build_dir, *dbtoolpath), - os.path.join('..', *(dbtoolpath + ['__init__.py'])))) - env.Execute(Copy(os.path.join(build_dir, *(dbtoolpath + ['utils'])), - os.path.join('..', *(dbtoolpath + ['utils', 'xmldepend.xsl'])))) - dbpath = dbtoolpath + ['docbook-xsl-1.76.1'] - env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['common'])))) - env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['lib'])))) - env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['html'])))) - env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['fo'])))) - env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['manpages'])))) - env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['epub'])))) - env.Execute(Mkdir(os.path.join(build_dir, *(dbpath + ['xhtml-1_1'])))) - env.Execute(Copy(os.path.join(build_dir, *dbpath), - os.path.join('..', *(dbpath + ['VERSION'])))) - for g in glob.glob(os.path.join('..', *(dbpath + ['common', '*.*']))): - env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['common'])), g)) - for g in glob.glob(os.path.join('..', *(dbpath + ['lib', '*.*']))): - env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['lib'])), g)) - for g in glob.glob(os.path.join('..', *(dbpath + ['html', '*.*']))): - env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['html'])), g)) - for g in glob.glob(os.path.join('..', *(dbpath + ['fo', '*.*']))): - env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['fo'])), g)) - for g in glob.glob(os.path.join('..', *(dbpath + ['manpages', '*.*']))): - env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['manpages'])), g)) - for g in glob.glob(os.path.join('..', *(dbpath + ['epub', '*.xsl']))): - env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['epub'])), g)) - for g in glob.glob(os.path.join('..', *(dbpath + ['xhtml-1_1', '*.*']))): - env.Execute(Copy(os.path.join(build_dir, *(dbpath + ['xhtml-1_1'])), g)) + # List of prerequisite files in the build/doc folder + buildsuite = [] + + def copy_dbfiles(env, toolpath, paths, fpattern, use_builddir=True): + """ Helper function, copies a bunch of files matching + the given fpattern to a target directory. + """ + global buildsuite + if not SCons.Util.is_List(toolpath): + toolpath = [toolpath] + if not SCons.Util.is_List(paths): + paths = [paths] + if not SCons.Util.is_List(fpattern): + fpattern = [fpattern] + + if use_builddir: + target_dir = env.Dir(os.path.join(build_dir, *(toolpath+paths))) + buildsuite.extend(env.GlobInstall(target_dir, + os.path.join('..', *(toolpath+paths+fpattern)))) + else: + target_dir = env.Dir(os.path.join(*(toolpath+paths))) + buildsuite.extend(env.GlobInstall(target_dir, + os.path.join(*(paths + fpattern)))) + + # + # Copy generated files (.gen/.mod/.xml) to the build folder + # + copy_dbfiles(env, build, 'generated', '*.gen', False) + copy_dbfiles(env, build, 'generated', '*.mod', False) + copy_dbfiles(env, build, ['generated','examples'], '*', False) - # - # Copy additional Tools (gs, zip) - # - toolpath = ['src', 'engine', 'SCons', 'Tool'] - env.Execute(Copy(os.path.join(build_dir, *toolpath), - os.path.join('..', *(toolpath + ['gs.py'])))) - env.Execute(Copy(os.path.join(build_dir, *toolpath), - os.path.join('..', *(toolpath + ['zip.py'])))) + # + # Copy XSLT files (.xslt) to the build folder + # + copy_dbfiles(env, build, 'xslt', '*.*', False) + # + # Copy DocBook stylesheets and Tool to the build folder + # + dbtoolpath = ['src', 'engine', 'SCons', 'Tool', 'docbook'] + copy_dbfiles(env, dbtoolpath, [], '__init__.py') + copy_dbfiles(env, dbtoolpath, 'utils', 'xmldepend.xsl') + dbpath = dbtoolpath + ['docbook-xsl-1.76.1'] + copy_dbfiles(env, dbpath, [], 'VERSION') + copy_dbfiles(env, dbpath, ['common'], '*.*') + copy_dbfiles(env, dbpath, ['lib'], '*.*') + copy_dbfiles(env, dbpath, ['html'], '*.*') + copy_dbfiles(env, dbpath, ['fo'], '*.*') + copy_dbfiles(env, dbpath, ['manpages'], '*.*') + copy_dbfiles(env, dbpath, ['epub'], '*.xsl') + copy_dbfiles(env, dbpath, ['xhtml-1_1'], '*.*') # - # Each document will live in its own subdirectory. List them here - # by their subfolder names. Note, how the specifiers for each subdir - # have nothing to do with which formats get created...but which - # of the outputs get installed to the build folder and added to - # the different source and binary packages in the end. + # Copy additional Tools (gs, zip) # - docs = {'design' : ['chtml','pdf'], - #'python10' : ['chtml','html','pdf'], - 'reference' : ['chtml','html','pdf'], - #'developer' : ['chtml','html','pdf'], - 'user' : ['chtml','html','pdf','epub'], - 'man' : ['man','epub'] + toolpath = ['src', 'engine', 'SCons', 'Tool'] + copy_dbfiles(env, toolpath, [], 'gs.py') + copy_dbfiles(env, toolpath, [], 'zip.py') + + # + # Each document will live in its own subdirectory "build/doc/xxx". + # List them here by their subfolder names. Note, how the specifiers + # for each subdir (=DOCTARGETS) have nothing to do with which + # formats get created...but which of the outputs get installed + # to the build folder and added to the different source and binary + # packages in the end. + # In addition to the list of target formats (DOCTARGETS), we also + # store some dependency information in this dict. The DOCDEPENDS + # list contains all files from each local "MANIFEST", after + # installing/copying them to the build directory. It basically + # links the original sources to the respective build folder, + # such that a simple 'python bootstrap.py' rebuilds the + # documentation when a file, like 'doc/user/depends.xml' + # for example, changes. + # Finally, in DOCNODES we store the created PDF and HTML files, + # such that we can then install them in the proper places for + # getting picked up by the archiving/packaging stages. + DOCTARGETS = 0 + DOCDEPENDS = 1 + DOCNODES = 2 + docs = {'design' : (['chunked','pdf'], [], []), + #'python10' : (['chunked','html','pdf'], [], []), + 'reference' : (['chunked','html','pdf'], [], []), + #'developer' : (['chunked','html','pdf'], [], []), + 'user' : (['chunked','html','pdf','epub','text'], [], []), + 'man' : (['man','epub','text'], [], []) } + # The names of the target files for the MAN pages man_page_list = ['scons.1','scons-time.1','sconsign.1'] @@ -216,15 +288,13 @@ else: continue base, ext = os.path.splitext(s) if ext in ['.fig', '.jpg']: - env.Execute(Copy(build, s)) + buildsuite.extend(env.Command(os.path.join(build, s), + s, + Copy("$TARGET", "$SOURCE"))) else: - revaction([env.File(os.path.join(build, s))], + revaction([env.File(os.path.join(build, s))], [env.File(s)], env) - # - # For each document, build the document itself in HTML, - # and PDF formats. - # for doc in docs: # @@ -232,8 +302,10 @@ else: # build directory, while branding them with the # SCons copyright and the current revision number... # - env.Execute(Mkdir(os.path.join(build, doc))) - env.Execute(Mkdir(os.path.join(build, doc, 'titlepage'))) + if not os.path.exists(os.path.join(build, doc)): + env.Execute(Mkdir(os.path.join(build, doc))) + if not os.path.exists(os.path.join(build, doc, 'titlepage')): + env.Execute(Mkdir(os.path.join(build, doc, 'titlepage'))) manifest = File(os.path.join(doc, 'MANIFEST')).rstr() src_files = bootstrap.parseManifestLines(doc, open(manifest).readlines()) for s in src_files: @@ -242,22 +314,56 @@ else: doc_s = os.path.join(doc, s) build_s = os.path.join(build, doc, s) base, ext = os.path.splitext(doc_s) + head, tail = os.path.split(s) + if head: + target_dir = os.path.join(build, doc, head) + else: + target_dir = os.path.join(build, doc) if ext in ['.fig', '.jpg', '.svg']: - env.Execute(Copy(build_s, doc_s)) + docs[doc][DOCDEPENDS].extend(env.Command(build_s, doc_s, + Copy("$TARGET", "$SOURCE"))) else: - revaction([env.File(build_s)], - [env.File(doc_s)], env) + btarget = env.File(build_s) + docs[doc][DOCDEPENDS].append(btarget) + revaction([btarget], [env.File(doc_s)], env) + + + # + # For each document, build the document itself in HTML, + # and PDF formats. + # + for doc in docs: # - # Call SCons in each local doc folder directly, such that - # we can Glob for the created *.html files afterwards to - # get the dependencies for the install targets right. + # Call SCons in each local doc folder # cleanopt = '' if env.GetOption('clean'): cleanopt = ' -c' - cmd = env.subst("cd %s && $PYTHON ${SCONS_PY.abspath}" % os.path.join(build, doc))+cleanopt - os.system(cmd) + scdir = os.path.join(build, doc) + sctargets = [] + if 'html' in docs[doc][DOCTARGETS]: + sctargets.append(env.File(os.path.join(scdir, 'index.html'))) + if 'chunked' in docs[doc][DOCTARGETS]: + sctargets.append(env.File(os.path.join(scdir, 'scons-%s' % doc, 'index.html'))) + if 'pdf' in docs[doc][DOCTARGETS]: + sctargets.append(env.File(os.path.join(scdir, 'scons-%s.pdf' % doc))) + if 'epub' in docs[doc][DOCTARGETS]: + sctargets.append(env.File(os.path.join(scdir, 'scons-%s.epub' % doc))) + + if 'man' in docs[doc][DOCTARGETS]: + for m in man_page_list: + sctargets.append(os.path.join(scdir, m)) + man, _1 = os.path.splitext(m) + + sctargets.append(os.path.join(scdir, 'scons-%s.pdf' % man)) + sctargets.append(os.path.join(scdir, 'scons-%s.html' % man)) + + docs[doc][DOCNODES].extend(env.Command(sctargets, buildsuite + docs[doc][DOCDEPENDS], + "cd %s && $PYTHON ${SCONS_PY.abspath}%s" % (scdir, cleanopt))) + + install_css = False + for doc in docs: # Collect the output files for this subfolder htmldir = os.path.join(build, 'HTML', 'scons-%s' % doc) @@ -265,37 +371,61 @@ else: html = os.path.join(build, 'HTML', 'scons-%s.html' % doc) pdf = os.path.join(build, 'PDF', 'scons-%s.pdf' % doc) epub = os.path.join(build, 'EPUB', 'scons-%s.epub' % doc) - if 'chtml' in docs[doc]: - env.Install(htmldir, Glob(os.path.join(build, doc,'scons-%s' % doc, '*.html'))) - tar_deps.extend([htmlindex]) + text = os.path.join(build, 'TEXT', 'scons-%s.txt' % doc) + if 'chunked' in docs[doc][DOCTARGETS]: + installed_chtml = env.ChunkedInstall(env.Dir(htmldir), + os.path.join(build, doc,'scons-%s' % doc, 'index.html')) + installed_chtml_css = env.Install(env.Dir(htmldir), + os.path.join(build, doc, 'scons.css')) + env.Depends(installed_chtml, docs[doc][DOCNODES]) + env.Depends(installed_chtml_css, docs[doc][DOCNODES]) + + tar_deps.extend([htmlindex, installed_chtml_css]) tar_list.extend([htmldir]) Local(htmlindex) env.Ignore(htmlindex, version_xml) - if 'html' in docs[doc]: - env.InstallAs(html, os.path.join(build, doc,'index.html')) + if 'html' in docs[doc][DOCTARGETS]: + env.InstallAs(env.File(html), env.File(os.path.join(build, doc,'index.html'))) tar_deps.extend([html]) tar_list.extend([html]) Local(html) env.Ignore(html, version_xml) + install_css = True - if 'pdf' in docs[doc]: - env.InstallAs(pdf, os.path.join(build, doc,'scons-%s.pdf' % doc)) + if 'pdf' in docs[doc][DOCTARGETS]: + env.InstallAs(env.File(pdf), env.File(os.path.join(build, doc,'scons-%s.pdf' % doc))) Local(pdf) env.Ignore(pdf, version_xml) tar_deps.append(pdf) tar_list.append(pdf) - if 'epub' in docs[doc] and gs: - env.InstallAs(epub, os.path.join(build, doc,'scons-%s.epub' % doc)) + if 'epub' in docs[doc][DOCTARGETS] and gs: + env.InstallAs(env.File(epub), env.File(os.path.join(build, doc,'scons-%s.epub' % doc))) Local(epub) env.Ignore(epub, version_xml) tar_deps.append(epub) tar_list.append(epub) - if 'man' in docs[doc]: + if ('text' in docs[doc][DOCTARGETS] and lynx and + (('html' in docs[doc][DOCTARGETS]) or (doc == 'man'))): + texthtml = os.path.join(build, doc,'index.html') + if doc == 'man': + # Special handling for single MAN file + texthtml = os.path.join(build, doc, 'scons-scons.html') + + env.Command(text, env.File(texthtml), "lynx -dump ${SOURCE.abspath} > $TARGET") + Local(text) + + env.Ignore(text, version_xml) + + tar_deps.append(text) + tar_list.append(text) + + + if 'man' in docs[doc][DOCTARGETS]: # # Man page(s) # @@ -305,13 +435,22 @@ else: pdf = os.path.join(build, 'PDF', '%s-man.pdf' % man) html = os.path.join(build, 'HTML' , '%s-man.html' % man) - env.InstallAs(pdf, os.path.join(build, 'man','scons-%s.pdf' % man)) - env.InstallAs(html, os.path.join(build, 'man','scons-%s.html' % man)) + env.InstallAs(env.File(pdf), env.File(os.path.join(build, 'man','scons-%s.pdf' % man))) + env.InstallAs(env.File(html), env.File(os.path.join(build, 'man','scons-%s.html' % man))) tar_deps.extend([pdf, html]) tar_list.extend([pdf, html]) + # Install CSS file, common to all single HTMLs + if install_css: + css_file = os.path.join(build, 'HTML', 'scons.css') + env.InstallAs(env.File(css_file), + env.File(os.path.join(build, 'user','scons.css'))) + tar_deps.extend([css_file]) + tar_list.extend([css_file]) + Local(css_file) + if not epydoc_cli: try: import epydoc |