From 75dd267e0f5b44603e6d33b835e2007bca5fefee Mon Sep 17 00:00:00 2001 From: Dirk Baechle Date: Wed, 12 Mar 2014 00:01:57 +0100 Subject: - improved dependency handling for doc toolchain (no false rebuilds anymore) - fixed EPUB builder - corrected anchor style for links in CSS - documents now include chapter in section numbering --- doc/SConscript | 264 ++++++++++++++++++++---------- doc/design/chtml.xsl | 1 + doc/design/html.xsl | 1 + doc/design/pdf.xsl | 1 + doc/design/scons.css | 4 +- doc/man/html.xsl | 1 + doc/man/pdf.xsl | 1 + doc/man/scons-time.xml | 55 +++---- doc/man/scons.css | 4 +- doc/man/scons.xml | 46 +++--- doc/man/sconsign.xml | 52 +++--- doc/reference/chtml.xsl | 1 + doc/reference/html.xsl | 1 + doc/reference/pdf.xsl | 1 + doc/reference/scons.css | 4 +- doc/user/chtml.xsl | 1 + doc/user/html.xsl | 1 + doc/user/pdf.xsl | 1 + doc/user/scons.css | 4 +- src/engine/SCons/Tool/docbook/__init__.py | 5 + 20 files changed, 275 insertions(+), 174 deletions(-) diff --git a/doc/SConscript b/doc/SConscript index c731dab..3f51030 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -104,7 +104,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,69 +182,64 @@ 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)) + # 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 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)) + # + # Copy XSLT files (.xslt) to the build folder + # + copy_dbfiles(env, build, 'xslt', '*.*', 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 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'], '*.*') + # + # Copy additional Tools (gs, zip) + # + 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. List them here @@ -195,13 +248,14 @@ else: # of the outputs get installed to the build folder and added to # the different source and binary packages in the end. # - docs = {'design' : ['chtml','pdf'], - #'python10' : ['chtml','html','pdf'], - 'reference' : ['chtml','html','pdf'], - #'developer' : ['chtml','html','pdf'], - 'user' : ['chtml','html','pdf','epub'], + docs = {'design' : ['chunked','pdf'], + #'python10' : ['chunked','html','pdf'], + 'reference' : ['chunked','html','pdf'], + #'developer' : ['chunked','html','pdf'], + 'user' : ['chunked','html','pdf','epub'], 'man' : ['man','epub'] } + # The names of the target files for the MAN pages man_page_list = ['scons.1','scons-time.1','sconsign.1'] @@ -216,15 +270,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 +284,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 +296,55 @@ 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)) + buildsuite.extend(env.Command(build_s, doc_s, + Copy("$TARGET", "$SOURCE"))) else: revaction([env.File(build_s)], [env.File(doc_s)], env) + + # + # For each document, build the document itself in HTML, + # and PDF formats. + # + docnodes = {} + 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]: + sctargets.append(env.File(os.path.join(scdir, 'index.html'))) + if 'chunked' in docs[doc]: + sctargets.append(env.File(os.path.join(scdir, 'scons-%s' % doc, 'index.html'))) + if 'pdf' in docs[doc]: + sctargets.append(env.File(os.path.join(scdir, 'scons-%s.pdf' % doc))) + if 'epub' in docs[doc]: + sctargets.append(env.File(os.path.join(scdir, 'scons-%s.epub' % doc))) + + if 'man' in docs[doc]: + 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)) + + docnodes[doc] = env.Command(sctargets, buildsuite, + "cd %s && $PYTHON ${SCONS_PY.abspath}%s" % (scdir, cleanopt)) + + for doc in docs: # Collect the output files for this subfolder htmldir = os.path.join(build, 'HTML', 'scons-%s' % doc) @@ -265,22 +352,25 @@ 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'))) + if 'chunked' in docs[doc]: + installed_chtml = env.ChunkedInstall(env.Dir(htmldir), + os.path.join(build, doc,'scons-%s' % doc, 'index.html')) + env.Depends(installed_chtml, docnodes[doc]) + tar_deps.extend([htmlindex]) 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')) + 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) if 'pdf' in docs[doc]: - env.InstallAs(pdf, os.path.join(build, doc,'scons-%s.pdf' % doc)) + env.InstallAs(env.File(pdf), env.File(os.path.join(build, doc,'scons-%s.pdf' % doc))) Local(pdf) env.Ignore(pdf, version_xml) @@ -288,7 +378,7 @@ else: tar_list.append(pdf) if 'epub' in docs[doc] and gs: - env.InstallAs(epub, os.path.join(build, doc,'scons-%s.epub' % doc)) + env.InstallAs(env.File(epub), env.File(os.path.join(build, doc,'scons-%s.epub' % doc))) Local(epub) env.Ignore(epub, version_xml) @@ -305,8 +395,8 @@ 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]) diff --git a/doc/design/chtml.xsl b/doc/design/chtml.xsl index 457f563..dde3c6f 100644 --- a/doc/design/chtml.xsl +++ b/doc/design/chtml.xsl @@ -33,6 +33,7 @@ + /appendix toc,title diff --git a/doc/design/html.xsl b/doc/design/html.xsl index 74ea529..9efc458 100644 --- a/doc/design/html.xsl +++ b/doc/design/html.xsl @@ -32,6 +32,7 @@ + /appendix toc,title diff --git a/doc/design/pdf.xsl b/doc/design/pdf.xsl index 652975f..33100d2 100644 --- a/doc/design/pdf.xsl +++ b/doc/design/pdf.xsl @@ -33,6 +33,7 @@ + 0pt diff --git a/doc/design/scons.css b/doc/design/scons.css index 6941abb..ff9b5a1 100644 --- a/doc/design/scons.css +++ b/doc/design/scons.css @@ -6,11 +6,11 @@ body { } -a { +a:link { color: #80572a; } -a:hover { +a:link:hover { color: #d72816; text-decoration: none; } diff --git a/doc/man/html.xsl b/doc/man/html.xsl index 864af88..714412a 100644 --- a/doc/man/html.xsl +++ b/doc/man/html.xsl @@ -32,6 +32,7 @@ + /appendix toc,title diff --git a/doc/man/pdf.xsl b/doc/man/pdf.xsl index f314103..c821dde 100644 --- a/doc/man/pdf.xsl +++ b/doc/man/pdf.xsl @@ -33,6 +33,7 @@ + 0pt diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml index d7b7c42..a1ecadf 100644 --- a/doc/man/scons-time.xml +++ b/doc/man/scons-time.xml @@ -1,39 +1,34 @@ - - - + - - - - - - + __COPYRIGHT__ - - + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: - - - - - - - + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. - + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - - - - - - +--> + + + SCONS-TIME 1 diff --git a/doc/man/scons.css b/doc/man/scons.css index 6941abb..ff9b5a1 100644 --- a/doc/man/scons.css +++ b/doc/man/scons.css @@ -6,11 +6,11 @@ body { } -a { +a:link { color: #80572a; } -a:hover { +a:link:hover { color: #d72816; text-decoration: none; } diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 60ecc6c..d726796 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1,4 +1,28 @@ + @@ -18,28 +42,6 @@ - - - - - - - - - - - - - - - - - - - - - - SCons &buildversion; diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml index 47fff56..ca99db6 100644 --- a/doc/man/sconsign.xml +++ b/doc/man/sconsign.xml @@ -1,36 +1,34 @@ + + - - - - - - - - - - - - - - - - - - - - - - - - - - - SCONSIGN 1 diff --git a/doc/reference/chtml.xsl b/doc/reference/chtml.xsl index 722aec1..d85874d 100644 --- a/doc/reference/chtml.xsl +++ b/doc/reference/chtml.xsl @@ -33,6 +33,7 @@ + /appendix toc,title diff --git a/doc/reference/html.xsl b/doc/reference/html.xsl index 74ea529..9efc458 100644 --- a/doc/reference/html.xsl +++ b/doc/reference/html.xsl @@ -32,6 +32,7 @@ + /appendix toc,title diff --git a/doc/reference/pdf.xsl b/doc/reference/pdf.xsl index 652975f..33100d2 100644 --- a/doc/reference/pdf.xsl +++ b/doc/reference/pdf.xsl @@ -33,6 +33,7 @@ + 0pt diff --git a/doc/reference/scons.css b/doc/reference/scons.css index 6941abb..ff9b5a1 100644 --- a/doc/reference/scons.css +++ b/doc/reference/scons.css @@ -6,11 +6,11 @@ body { } -a { +a:link { color: #80572a; } -a:hover { +a:link:hover { color: #d72816; text-decoration: none; } diff --git a/doc/user/chtml.xsl b/doc/user/chtml.xsl index e292c88..e855c31 100644 --- a/doc/user/chtml.xsl +++ b/doc/user/chtml.xsl @@ -33,6 +33,7 @@ + /appendix toc,title diff --git a/doc/user/html.xsl b/doc/user/html.xsl index c275c3d..17dc189 100644 --- a/doc/user/html.xsl +++ b/doc/user/html.xsl @@ -32,6 +32,7 @@ + /appendix toc,title diff --git a/doc/user/pdf.xsl b/doc/user/pdf.xsl index 9c54592..2c0d086 100644 --- a/doc/user/pdf.xsl +++ b/doc/user/pdf.xsl @@ -33,6 +33,7 @@ + 0pt diff --git a/doc/user/scons.css b/doc/user/scons.css index 6941abb..ff9b5a1 100644 --- a/doc/user/scons.css +++ b/doc/user/scons.css @@ -6,11 +6,11 @@ body { } -a { +a:link { color: #80572a; } -a:hover { +a:link:hover { color: #d72816; text-decoration: none; } diff --git a/src/engine/SCons/Tool/docbook/__init__.py b/src/engine/SCons/Tool/docbook/__init__.py index 72ea175..aacc26d 100644 --- a/src/engine/SCons/Tool/docbook/__init__.py +++ b/src/engine/SCons/Tool/docbook/__init__.py @@ -429,6 +429,11 @@ def DocbookEpub(env, target, source=None, *args, **kw): mime_file.close() zf.write(mime_file.name, compress_type = zipfile.ZIP_STORED) for s in source: + if os.path.isfile(str(s)): + head, tail = os.path.split(str(s)) + if not head: + continue + s = head for dirpath, dirnames, filenames in os.walk(str(s)): for fname in filenames: path = os.path.join(dirpath, fname) -- cgit v0.12