Merge pull request #4510 from mwichmann/doc/build-no-pdf

Extend pdf-skipping to man and user builds.

Author: bdbaddog

CHANGES.txt

@@ -32,6 +32,12 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       ones in parent NodeInfoBase and can just be inherited.
     - Update manpage for Tools, and for TOOL, which also gets a minor
       tweak for how it's handled (should be more accurate in a few situations).
+    - Documentation build now properly passes through skipping the PDF
+      (and EPUB) builds of manpage and user guide; this can also be done
+      manually if directly calling doc/man/SConstruct and doc/user/SConstruct
+      by adding SKIP_PDF=1.  This should help with distro packaging of SCons,
+      which now does not need "fop" and other tools to be set up in order to
+      build pdf versions which are then ignored.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -69,7 +69,13 @@ DOCUMENTATION
 DEVELOPMENT
 -----------
 
-- List visible changes in the way SCons is developed
+- Documentation build now properly passes through skipping the PDF
+  (and EPUB) builds of manpage and user guide; this can also be done
+  manually if directly calling doc/man/SConstruct and doc/user/SConstruct
+  by adding SKIP_PDF=1. This should help with distro packaging of SCons,
+  which now does not need "fop" and other tools to be set up in order to
+  build pdf versions which are then ignored.
+
 
 Thanks to the following contributors listed below for their contributions to this release.
 ==========================================================================================

doc/SConscript

@@ -490,11 +490,13 @@ else:
                     sctargets.append(os.path.join(scdir, f'scons-{man}.pdf'))
                 sctargets.append(os.path.join(scdir, f'scons-{man}.html'))
 
+        # pass on the information to skip PDF/EPUB when calling man/guide SConstruct
+        skip_str = "SKIP_PDF=1" if skip_pdf_build else ""
         nodes.extend(
             env.Command(
                 target=sctargets,
                 source=buildsuite + depends,
-                action="cd %s && $PYTHON ${SCONS_PY.abspath}%s" % (scdir, cleanopt),
+                action="cd %s && $PYTHON ${SCONS_PY.abspath}%s %s" % (scdir, cleanopt, skip_str),
             )
         )
 
@@ -545,7 +547,7 @@ else:
             tar_deps.append(pdf)
             tar_list.append(pdf)
 
-        if 'epub' in targets and gs:
+        if 'epub' in targets and not skip_pdf_build and gs:
             env.InstallAs(
                 target=env.File(epub),
                 source=env.File(os.path.join(build, doc, f'scons-{doc}.epub')),

doc/man/SConstruct

@@ -1,51 +1,40 @@
-#
-# SConstruct file for building SCons documentation.
-#
+# SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
+# SPDX-License-Identifier: MIT
 
-#
-# __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.
+"""
+SConstruct file for building SCons manpages.
+
+This is usually invoked as a separate build by the top-level SCons build.
+
+If invoked directly, can add SKIP_PDF=1 to avoid pdf and epub generation.
+"""
 
 import os
 
-env = Environment(ENV={'PATH' : os.environ['PATH']},
-                  tools=['docbook','gs','zip'],
-                  toolpath=['../../SCons/Tool'],
-                  DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
-                  DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl')
+env = Environment(
+    ENV={'PATH': os.environ['PATH']},
+    tools=['docbook', 'gs', 'zip'],
+    toolpath=['../../SCons/Tool'],
+    DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
+    DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl',
+)
 
+skip_pdf = ARGUMENTS.get('SKIP_PDF', False)
 has_pdf = False
-if (env.WhereIs('fop') or 
-    env.WhereIs('xep')):
+if not skip_pdf and any((env.WhereIs('fop'), env.WhereIs('xep'))):
     has_pdf = True
 
 # Helper function, combining all the steps for a single target
 def createManPages(env, target):
     env.DocbookXInclude('%s_xi.xml' % target, '%s.xml' % target)
-    env.DocbookXslt('%s_db.xml' % target, '%s_xi.xml' % target, 
-                    xsl='../xslt/to_docbook.xslt')
-    env.DocbookHtml('scons-%s.html' % target,'%s_db.xml' % target)
+    env.DocbookXslt(
+        '%s_db.xml' % target, '%s_xi.xml' % target, xsl='../xslt/to_docbook.xslt'
+    )
+    env.DocbookHtml('scons-%s.html' % target, '%s_db.xml' % target)
     env.DocbookMan('%s.1' % target, '%s_db.xml' % target)
     if has_pdf:
-        env.DocbookPdf('scons-%s.pdf' % target,'%s_db.xml' % target)
+        env.DocbookPdf('scons-%s.pdf' % target, '%s_db.xml' % target)
+
 
 #
 # Create MAN pages
@@ -62,7 +51,10 @@ if env.WhereIs('gs'):
 # Create the EPUB format
 #
 if has_gs and has_pdf:
-    jpg = env.Gs('OEBPS/cover.jpg','scons-scons.pdf', 
-                 GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -dJPEGQ=100 -r72x72 -q')
+    jpg = env.Gs(
+        'OEBPS/cover.jpg',
+        'scons-scons.pdf',
+        GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -dJPEGQ=100 -r72x72 -q',
+    )
     epub = env.DocbookEpub('scons-man.epub', 'scons_db.xml', xsl='epub.xsl')
     env.Depends(epub, jpg)

doc/user/SConstruct

@@ -1,8 +1,13 @@
 # SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
 # SPDX-License-Identifier: MIT
-#
-# SConstruct file for building SCons documentation.
-#
+
+"""
+SConstruct file for building SCons User Guide..
+
+This is usually invoked as a separate build by the top-level SCons build.
+
+If invoked directly, can add SKIP_PDF=1 to avoid pdf and epub generation.
+"""
 
 import os
 
@@ -16,8 +21,9 @@ env = Environment(
     DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl',
 )
 
+skip_pdf = ARGUMENTS.get('SKIP_PDF', False)
 has_pdf = False
-if env.WhereIs('fop') or env.WhereIs('xep'):
+if not skip_pdf and any((env.WhereIs('fop'), env.WhereIs('xep'))):
     has_pdf = True
 
 #

site_scons/BuildCommandLine.py

@@ -79,6 +79,7 @@ def init_command_line_variables(self):
                 "SKIP_DOC=",
                 "Skip building documents. The value can be 'pdf', 'api', "
                 "''all' or 'none'. A comma-separated list is also allowed. "
+                "Do not set this for an official release build. "
                 "The default is 'none' (build all docs)"
             ),
         ]