From 0ebf8857e5ef844c7902bfa368159de8f41de5cd Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 2 Apr 2024 10:48:01 -0600 Subject: Extend pdf-skipping to man and user builds. An earlier change extended SKIP_DOC as a CLI argument at the top level to allow granularity - can specify pdf and/or api to skip those. Skipping the pdf build didn't entirely work, as the build re-invokes SCons which is then a fresh context. That information is now passed on the command line to those two builds, and if invokved directly (as Debian packaging does), SKIP_PDF=1 can be added on the command line. Signed-off-by: Mats Wichmann --- CHANGES.txt | 6 ++++ RELEASE.txt | 8 ++++- doc/SConscript | 6 ++-- doc/man/SConstruct | 66 +++++++++++++++++++----------------------- doc/user/SConstruct | 14 ++++++--- site_scons/BuildCommandLine.py | 1 + 6 files changed, 57 insertions(+), 44 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index c57a37a..1d6c9c6 100644 --- a/CHANGES.txt +++ b/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 diff --git a/RELEASE.txt b/RELEASE.txt index 5473bc0..12d4b07 100644 --- a/RELEASE.txt +++ b/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. ========================================================================================== diff --git a/doc/SConscript b/doc/SConscript index 29f2bbf..a15c71e 100644 --- a/doc/SConscript +++ b/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')), diff --git a/doc/man/SConstruct b/doc/man/SConstruct index 4a2fabd..5c6d4fa 100644 --- a/doc/man/SConstruct +++ b/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) diff --git a/doc/user/SConstruct b/doc/user/SConstruct index b64482b..69792ae 100644 --- a/doc/user/SConstruct +++ b/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 # diff --git a/site_scons/BuildCommandLine.py b/site_scons/BuildCommandLine.py index 32e62f3..5d00f6e 100644 --- a/site_scons/BuildCommandLine.py +++ b/site_scons/BuildCommandLine.py @@ -79,6 +79,7 @@ class BuildCommandLine: "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)" ), ] -- cgit v0.12