Merge pull request SCons#4707 from mwichmann/doc/doctools

Update docs for `SConsDoc` and `SConsExample`

Author: bdbaddog

CHANGES.txt

@@ -27,6 +27,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - runtest.py once again finds "external" tests, such as the tests for
       tools in scons-contrib. An earlier rework had broken this.  Fixes #4699.
     - Clarify how pre/post actions on an alias work.
+    - Tweak the two doc-generation modules. The significant change is
+      turning the introductory comment in bin/SConsExamples into a docstring
+      that can be rendered by Sphinx, and updating that text. The rest is
+      minor fiddling like switching to f-strings small doc changes.
     - Fix a couple of unit tests to not fail with Python 3.14. These involve
       bytecode and error message contents, and there was no problem with
       SCons itself using 3.14 in its current (just-before-freeze) state.

bin/SConsDoc.py

@@ -3,7 +3,9 @@
 # SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
 # SPDX-License-Identifier: MIT
 
-"""Module for handling SCons documentation processing.
+"""
+SCons Documentation Processing module
+=====================================
 
 This module parses home-brew XML files that document important SCons
 components.  Currently it handles Builders, Environment functions/methods,
@@ -18,6 +20,8 @@
 
 Builder example:
 
+.. code-block:: xml
+
     <builder name="BUILDER">
     <summary>
     <para>This is the summary description of an SCons Builder.
@@ -29,7 +33,7 @@
     interpolated by specifying the &b-link-BUILDER; element.
     </para>
 
-    Unlike normal XML, blank lines are significant in these
+    Unlike vanilla DocBook, blank lines are significant in these
     descriptions and serve to separate paragraphs.
     They'll get replaced in DocBook output with appropriate tags
     to indicate a new paragraph.
@@ -42,6 +46,8 @@
 
 Function example:
 
+.. code-block:: xml
+
     <scons_function name="FUNCTION">
     <arguments signature="SIGTYPE">
     (arg1, arg2, key=value)
@@ -74,6 +80,8 @@
 
 Construction variable example:
 
+.. code-block:: xml
+
     <cvar name="VARIABLE">
     <summary>
     <para>This is the summary description of a construction variable.
@@ -93,6 +101,8 @@
 
 Tool example:
 
+.. code-block:: xml
+
     <tool name="TOOL">
     <summary>
     <para>This is the summary description of an SCons Tool.
@@ -223,7 +233,7 @@ def addEntity(self, name, uri):
         self.entries.append(DoctypeEntity(name, uri))
 
     def createDoctype(self):
-        content = '<!DOCTYPE %s [\n' % self.name
+        content = f'<!DOCTYPE {self.name} [\n'
         for e in self.entries:
             content += e.getEntityString()
         content += ']>\n'
@@ -318,7 +328,7 @@ def prettyPrintFile(fpath):
 
     @staticmethod
     def decorateWithHeader(root):
-        root.attrib["{"+xsi+"}schemaLocation"] = "%s %s/scons.xsd" % (dbxsd, dbxsd)
+        root.attrib["{"+xsi+"}schemaLocation"] = f"{dbxsd} {dbxsd}/scons.xsd"
         return root
 
     def newXmlTree(self, root):
@@ -340,22 +350,22 @@ def validateXml(fpath, xmlschema_context):
         try:
             doc = etree.parse(fpath)
         except Exception as e:
-            print("ERROR: %s fails to parse:"%fpath)
+            print(f"ERROR: {fpath} fails to parse:")
             print(e)
             return False
         doc.xinclude()
         try:
             TreeFactory.xmlschema.assertValid(doc)
         except etree.XMLSchemaValidateError as e:
-            print("ERROR: %s fails to validate:" % fpath)
+            print(f"ERROR: {fpath} fails to validate:")
             print(e)
             print(e.error_log.last_error.message)
-            print("In file: [%s]" % e.error_log.last_error.filename)
+            print(f"In file: [{e.error_log.last_error.filename}]")
             print("Line   : %d" % e.error_log.last_error.line)
             return False
 
         except Exception as e:
-            print("ERROR: %s fails to validate:" % fpath)
+            print(f"ERROR: {fpath} fails to validate:")
             print(e)
 
             return False
@@ -365,14 +375,14 @@ def validateXml(fpath, xmlschema_context):
     def findAll(root, tag, ns=None, xp_ctxt=None, nsmap=None):
         expression = ".//{%s}%s" % (nsmap[ns], tag)
         if not ns or not nsmap:
-            expression = ".//%s" % tag
+            expression = f".//{tag}"
         return root.findall(expression)
 
     @staticmethod
     def findAllChildrenOf(root, tag, ns=None, xp_ctxt=None, nsmap=None):
         expression = "./{%s}%s/*" % (nsmap[ns], tag)
         if not ns or not nsmap:
-            expression = "./%s/*" % tag
+            expression = f"./{tag}/*"
         return root.findall(expression)
 
     @staticmethod
@@ -495,7 +505,7 @@ def __str__(self):
         result = []
         for m in re.findall(r'([a-zA-Z/_]+|[^a-zA-Z/_]+)', s):
             if ' ' in m:
-                m = '"%s"' % m
+                m = f'"{m}"'
             result.append(m)
         return ' '.join(result)
     def append(self, data):