Merge pull request #4797 from mwichmann/doc/sphinx-ignore-all

Improve coverage of API doc build

Author: bdbaddog

CHANGES.txt

@@ -32,6 +32,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Handle the default (unset) ProgressObject differently for the sole
       purpose of avoiding Sphinx 9.0+ blowing up on it (it's been giving
       a warning for years, but now it's a fatal error).
+    - Improve covarage of API doc build by ignoring any setting of
+      __all__ in a package and not showing inherited members from optparse.
 
 
 RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700

RELEASE.txt

@@ -67,6 +67,10 @@ DOCUMENTATION
   a warning for years, but now it's a fatal error). Affects only the
   API doc build.
 
+- Improve covarage of API doc build by ignoring any setting of
+  __all__ in a package and not showing inherited members from optparse.
+
+
 
 DEVELOPMENT
 -----------

SCons/Script/SConsOptions.py

@@ -68,7 +68,7 @@ def diskcheck_convert(value):
 
 
 class SConsValues(optparse.Values):
-    """Holder class for uniform access to SCons options.
+    """SCons parsed argument names and values.
 
     A SCons option value can originate three different ways:
 
@@ -235,8 +235,8 @@ def set_option(self, name: str, value) -> None:
 class SConsOption(optparse.Option):
     """SCons added option.
 
-    Changes :attr:`CHECK_METHODS` and :attr:`CONST_ACTIONS` settings from
-    :class:`optparse.Option` base class to tune for our usage.
+    Changes :attr:`CHECK_METHODS` and :attr:`CONST_ACTIONS` settings
+    to tune for our usage.
 
     New function :meth:`_check_nargs_optional` implements the ``nargs=?``
     syntax from :mod:`argparse`, and is added to the ``CHECK_METHODS`` list.
@@ -247,12 +247,13 @@ class SConsOption(optparse.Option):
        set in the option. A parameter to mark the option settable was added
        in 4.8.0, but was not initially made part of the option object itself.
     """
+
     # can uncomment to have a place to trap SConsOption creation for debugging:
     # def __init__(self, *args, **kwargs):
     #     super().__init__(*args, **kwargs)
 
     def convert_value(self, opt: str, value):
-        """SCons override: recognize nargs="?"."""
+        """SCons override: recognize ``nargs='?'`"""
         if value is not None:
             if self.nargs in (1, '?'):
                 return self.check_value(opt, value)
@@ -289,7 +290,7 @@ def _check_nargs_optional(self) -> None:
 
 
 class SConsOptionGroup(optparse.OptionGroup):
-    """A subclass for SCons-specific option groups.
+    """SCons option groups.
 
     The only difference between this and the base class is that we print
     the group's help text flush left, underneath their own title but
@@ -311,7 +312,7 @@ def format_help(self, formatter) -> str:
 
 
 class SConsBadOptionError(optparse.BadOptionError):
-    """Raised if an invalid option value is encountered on the command line.
+    """SCons handler for bad options.
 
     Attributes:
        opt_str: The unrecognized command-line option.
@@ -328,6 +329,8 @@ def __str__(self) -> str:
 
 
 class SConsOptionParser(optparse.OptionParser):
+    """SCons option parser."""
+
     preserve_unknown_options = False
     raise_exception_on_error = False
 
@@ -343,13 +346,11 @@ def error(self, msg: str) -> None:
     def _process_long_opt(self, rargs, values) -> None:
         """SCons-specific processing of long options.
 
-        This is copied directly from the normal Optparse
-        :meth:`~optparse.OptionParser._process_long_opt` method, except
-        that, if configured to do so, we catch the exception thrown
-        when an unknown option is encountered and just stick it back
-        on the "leftover" arguments for later (re-)processing. This is
-        because we may see the option definition later, while processing
-        SConscript files.
+        Vendors :meth:`~optparse.OptionParser._process_long_opt`.
+        If configured to do so, catch the unknown option exception and stick
+        the option back on the "leftover" arguments for later (re-)processing.
+        This is because we may see the option definition later in the form
+        of a :meth:`~SCons.Script.Main.AddOption` while reading SConscript files.
         """
         arg = rargs.pop(0)
 
@@ -420,13 +421,11 @@ def _process_long_opt(self, rargs, values) -> None:
     def _process_short_opts(self, rargs, values) -> None:
         """SCons-specific processing of short options.
 
-        This is copied directly from the normal Optparse
-        :meth:`~optparse.OptionParser._process_short_opts` method, except
-        that, if configured to do so, we catch the exception thrown
-        when an unknown option is encountered and just stick it back
-        on the "leftover" arguments for later (re-)processing. This is
-        because we may see the option definition later, while processing
-        SConscript files.
+        Vendors :meth:`~optparse.OptionParser._process_short_opts`.
+        If configured to do so, catch the unknown option exception and stick
+        the option back on the "leftover" arguments for later (re-)processing.
+        This is because we may see the option definition later in the form
+        of a :meth:`~SCons.Script.Main.AddOption` while reading SConscript files.
         """
         arg = rargs.pop(0)
         stop = False
@@ -549,7 +548,7 @@ def add_local_option(self, *args, **kw) -> SConsOption:
         by default "local" (project-added) options are not eligible for
         :func:`~SCons.Script.Main.SetOption` calls.
 
-        .. versionchanged:: NEXT_VERSION
+        .. versionchanged:: 4.9.0
            If the option's *settable* attribute is true, it is added to
            the :attr:`SConsValues.settable` list. *settable* handling was
            added in 4.8.0, but was not made an option attribute at the time.
@@ -617,6 +616,12 @@ def print_local_option_help(self, file=None):
 
 
 class SConsIndentedHelpFormatter(optparse.IndentedHelpFormatter):
+    """SCons help formatting.
+
+    This is the SCons-specific :meth:`~optparse.HelpFormatter` subclass,
+    implemented by extending :meth:`optparse.IndentedHelpFormatter`.
+    """
+
     def format_usage(self, usage) -> str:
         """Format the usage message for SCons."""
         return "usage: %s\n" % usage
@@ -625,7 +630,7 @@ def format_heading(self, heading):
         """Translate heading to "SCons Options"
 
         Heading of "Options" changed to "SCons Options."
-        Unfortunately, we have to do this here, because those titles
+        Unfortunately, we have to intercept it here, because those titles
         are hard-coded in the optparse calls.
         """
         if heading == 'Options':
@@ -635,8 +640,8 @@ def format_heading(self, heading):
     def format_option(self, option):
         """SCons-specific option formatter.
 
-        A copy of the :meth:`optparse.IndentedHelpFormatter.format_option`
-        method.  Overridden so we can modify text wrapping to our liking:
+        Vendors :meth:`optparse.HelpFormatter.format_option`, overridden
+        to modify text wrapping to our liking:
 
         * add our own regular expression that doesn't break on hyphens
           (so things like ``--no-print-directory`` don't get broken).
@@ -663,8 +668,9 @@ def format_option(self, option):
                   read data from FILENAME
 
         Help strings are wrapped for terminal width and do not preserve
-        any hand-made formatting that may have been used in the ``AddOption``
-        call, so don't attempt prettying up a list of choices (for example).
+        any hand-made formatting that may have been used in the
+        :meth:`~SCons.Script.Main.AddOption` call, so don't attempt
+        prettying up a list of choices (for example).
         """
         result = []
         opts = self.option_strings[option]

SCons/Variables/__init__.py

@@ -21,7 +21,12 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-"""Adds user-friendly customizable variables to an SCons build."""
+"""
+Adds user-friendly customizable variables to an SCons build.
+
+"Build Variables" represent a way to supply values for SCons
+construction variables from the command-line, or from saved settings files.
+"""
 
 from __future__ import annotations
 
@@ -56,8 +61,27 @@
 
 @dataclass(order=True)
 class Variable:
-    """A Build Variable."""
-    __slots__ = ('key', 'aliases', 'help', 'default', 'validator', 'converter', 'do_subst')
+    """A Build Variable.
+
+    Attributes:
+       key: the name of the variable
+       aliases: other names recognized for the variable
+       help:– help text
+       default: optional default value
+       validator: optional validator function
+       converter: optional converter function
+       do_subst: substitute before calling converter/valiator (default True)
+    """
+
+    __slots__ = (
+        'key',
+        'aliases',
+        'help',
+        'default',
+        'validator',
+        'converter',
+        'do_subst',
+    )
     key: str
     aliases: list[str]
     help: str

doc/sphinx/SCons.Script.rst

@@ -33,6 +33,7 @@ SCons.Script.SConsOptions module
 --------------------------------
 
 .. automodule:: SCons.Script.SConsOptions
+    :no-inherited-members:
     :members:
     :undoc-members:
     :show-inheritance:

doc/sphinx/SCons.Variables.rst

@@ -5,6 +5,7 @@ Module contents
 ---------------
 
 .. automodule:: SCons.Variables
+    :ignore-module-all:
     :members:
     :undoc-members:
     :show-inheritance:
@@ -17,6 +18,7 @@ SCons.Variables.BoolVariable module
 -----------------------------------
 
 .. automodule:: SCons.Variables.BoolVariable
+    :ignore-module-all:
     :members:
     :undoc-members:
     :show-inheritance:
@@ -25,6 +27,7 @@ SCons.Variables.EnumVariable module
 -----------------------------------
 
 .. automodule:: SCons.Variables.EnumVariable
+    :ignore-module-all:
     :members:
     :undoc-members:
     :show-inheritance:
@@ -33,6 +36,8 @@ SCons.Variables.ListVariable module
 -----------------------------------
 
 .. automodule:: SCons.Variables.ListVariable
+    :ignore-module-all:
+    :no-inherited-members:
     :members:
     :undoc-members:
     :show-inheritance:
@@ -41,6 +46,7 @@ SCons.Variables.PackageVariable module
 --------------------------------------
 
 .. automodule:: SCons.Variables.PackageVariable
+    :ignore-module-all:
     :members:
     :undoc-members:
     :show-inheritance:
@@ -49,6 +55,7 @@ SCons.Variables.PathVariable module
 -----------------------------------
 
 .. automodule:: SCons.Variables.PathVariable
+    :ignore-module-all:
     :members:
     :undoc-members:
     :show-inheritance: