From 9d972b5a91f0fd2e3fe77728791cc8fda57f9db3 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 11 Mar 2024 09:02:56 -0600 Subject: Tweak documentation build [skip appveyor] Simplify the handling of info for each doc, avoid constructs like docs[doc][DOCDEPENDS].append(btarget) by unpacking the doc values. This is part 1 of a small rework. Signed-off-by: Mats Wichmann --- doc/SConscript | 86 ++++++++++++++++++++++++---------------------------------- 1 file changed, 36 insertions(+), 50 deletions(-) diff --git a/doc/SConscript b/doc/SConscript index cb92b41..60831bc 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -311,28 +311,22 @@ else: 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. + # Each document will build in its own subdirectory of "build/doc/". + # The *docs* dictionary entries have the document (and thus directory) + # name as the key, and a tuple of lists as the value. # - # 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. + # The first list is the document formats enabled ("targets"). Note this + # isn't what gets built, but what gets installed into the build folder + # source/target lists. + # + # The second list ("depends") is for dependency information. Dependencies + # are extracted from each local "MANIFEST" and added to this list. + # This basically links the original sources to the respective build folder. + # + # The third list ("nodes") stores the created PDF and HTML files, + # so that we can then install them in the proper places for getting + # picked up by the archiving/packaging stages. # - # 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'], [], []), @@ -401,7 +395,7 @@ else: else: revaction([env.File(os.path.join(build, s))], [env.File(s)], env) - for doc in docs: + for doc, (targets, depends, nodes) in docs.items(): # Read MANIFEST file and copy the listed files to the build directory, # while branding them with the SCons copyright and the current # revision number... @@ -423,58 +417,50 @@ else: else: target_dir = os.path.join(build, doc) if ext in ['.fig', '.jpg', '.svg']: - docs[doc][DOCDEPENDS].extend( + depends.extend( env.Command(build_s, doc_s, Copy("$TARGET", "$SOURCE")) ) else: btarget = env.File(build_s) - docs[doc][DOCDEPENDS].append(btarget) + depends.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: - - # + # For each document, add targets for each of the selected formats + for doc, (targets, depends, nodes) in docs.items(): # Call SCons in each local doc folder - # cleanopt = '' if env.GetOption('clean'): cleanopt = ' -c' scdir = os.path.join(build, doc) sctargets = [] - if 'html' in docs[doc][DOCTARGETS]: + if 'html' in targets: sctargets.append(env.File(os.path.join(scdir, 'index.html'))) - if 'chunked' in docs[doc][DOCTARGETS]: + if 'chunked' in targets: sctargets.append( env.File(os.path.join(scdir, f'scons-{doc}', 'index.html')) ) - if 'pdf' in docs[doc][DOCTARGETS]: + if 'pdf' in targets: sctargets.append(env.File(os.path.join(scdir, f'scons-{doc}.pdf'))) - if 'epub' in docs[doc][DOCTARGETS]: + if 'epub' in targets: sctargets.append(env.File(os.path.join(scdir, f'scons-{doc}.epub'))) - if 'man' in docs[doc][DOCTARGETS]: + if 'man' in targets: 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, f'scons-{man}.pdf')) sctargets.append(os.path.join(scdir, f'scons-{man}.html')) - docs[doc][DOCNODES].extend( + nodes.extend( env.Command( target=sctargets, - source=buildsuite + docs[doc][DOCDEPENDS], + source=buildsuite + depends, action="cd %s && $PYTHON ${SCONS_PY.abspath}%s" % (scdir, cleanopt), ) ) install_css = False - for doc in docs: - + for doc, (targets, depends, nodes) in docs.items(): # Collect the output files for this subfolder htmldir = os.path.join(build, 'HTML', f'scons-{doc}') htmlindex = os.path.join(htmldir, 'index.html') @@ -482,7 +468,7 @@ else: pdf = os.path.join(build, 'PDF', f'scons-{doc}.pdf') epub = os.path.join(build, 'EPUB', f'scons-{doc}.epub') text = os.path.join(build, 'TEXT', f'scons-{doc}.txt') - if 'chunked' in docs[doc][DOCTARGETS]: + if 'chunked' in targets: installed_chtml = env.ChunkedInstall( env.Dir(htmldir), os.path.join(build, doc, f'scons-{doc}', 'index.html'), @@ -490,15 +476,15 @@ else: 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]) + env.Depends(installed_chtml, nodes) + env.Depends(installed_chtml_css, nodes) tar_deps.extend([htmlindex, installed_chtml_css]) tar_list.extend([htmldir]) Local(htmlindex) env.Ignore(htmlindex, version_xml) - if 'html' in docs[doc][DOCTARGETS]: + if 'html' in targets: env.InstallAs( target=env.File(html), source=env.File(os.path.join(build, doc, 'index.html')), @@ -509,7 +495,7 @@ else: env.Ignore(html, version_xml) install_css = True - if 'pdf' in docs[doc][DOCTARGETS]: + if 'pdf' in targets: env.InstallAs( target=env.File(pdf), source=env.File(os.path.join(build, doc, f'scons-{doc}.pdf')), @@ -520,7 +506,7 @@ else: tar_deps.append(pdf) tar_list.append(pdf) - if 'epub' in docs[doc][DOCTARGETS] and gs: + if 'epub' in targets and gs: env.InstallAs( target=env.File(epub), source=env.File(os.path.join(build, doc, f'scons-{doc}.epub')), @@ -532,9 +518,9 @@ else: tar_list.append(epub) if ( - 'text' in docs[doc][DOCTARGETS] + 'text' in targets and lynx - and (('html' in docs[doc][DOCTARGETS]) or (doc == 'man')) + and ('html' in targets or doc == 'man') ): texthtml = os.path.join(build, doc, 'index.html') if doc == 'man': @@ -553,7 +539,7 @@ else: tar_deps.append(text) tar_list.append(text) - if 'man' in docs[doc][DOCTARGETS]: + if 'man' in targets: for m in man_page_list: man, _1 = os.path.splitext(m) -- cgit v0.12