Merge pull request SCons#4492 from mwichmann/build/doc-options

Tweak documentation build

Author: bdbaddog

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,82 +417,74 @@ 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')
         html = os.path.join(build, 'HTML', f'scons-{doc}.html')
         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'),
             )
             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)