API Docs build adjustment.

For a "package" which has a main piece and submodules, the main part is now processed before, rather than after, the submodules. Usally there's introductory material (e.g. in the main module's docstring) and it's more useful for this to appear at the top of a page rather than down after all the submodules. Made some docstring tweaks in two modules where the result didn't look very good - Debug and PathList. For PathList, Sphinx doesn't process both a class docstring and its __init__ method's docstring - you get one of the other, so joined those together. Signed-off-by: Mats Wichmann <[email protected]>
SCons · May 16, 2024 · 53fccd8 · 53fccd8
1 parent c33bb1a
commit 53fccd8
Show file tree

Hide file tree

Showing 11 changed files with 127 additions and 98 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -63,6 +63,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       old Python 2-only code block in a test.
     - scons-time tests now supply a "filter" argument to tarfile.extract
       to quiet a warning which was added in Python 3.13 beta 1.
+    - Restructured API docs build (Sphinx) so main module contents appear
+      on a given page *before* the submodule docs, not after. Also
+      tweaked the Util package doc build so it's structured more like the
+      other packages (a missed part of the transition when it was split).
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

diff --git a/RELEASE.txt b/RELEASE.txt
@@ -69,6 +69,8 @@ DOCUMENTATION
 - Updated Value Node docs.
 - Update manpage for Tools, and for the TOOL variable.
 - Update manpage and user guide for Variables usage.
+- Restructured API Docs build so main package contents are listed
+  before contents of package submodules.
 
 
 

diff --git a/SCons/Debug.py b/SCons/Debug.py
@@ -23,10 +23,10 @@
 
 """Code for debugging SCons internal things.
 
-Shouldn't be needed by most users. Quick shortcuts:
+Shouldn't be needed by most users. Quick shortcuts::
 
-from SCons.Debug import caller_trace
-caller_trace()
+    from SCons.Debug import caller_trace
+    caller_trace()
 """
 
 import atexit

diff --git a/SCons/PathList.py b/SCons/PathList.py
@@ -23,7 +23,7 @@
 
 """Handle lists of directory paths.
 
-These are the path lists that get set as CPPPATH, LIBPATH,
+These are the path lists that get set as ``CPPPATH``, ``LIBPATH``,
 etc.) with as much caching of data and efficiency as we can, while
 still keeping the evaluation delayed so that we Do the Right Thing
 (almost) regardless of how the variable is specified.
@@ -47,10 +47,10 @@ def node_conv(obj):
     """
     This is the "string conversion" routine that we have our substitutions
     use to return Nodes, not strings.  This relies on the fact that an
-    EntryProxy object has a get() method that returns the underlying
-    Node that it wraps, which is a bit of architectural dependence
-    that we might need to break or modify in the future in response to
-    additional requirements.
+    :class:`~SCons.Node.FS.EntryProxy` object has a ``get()`` method that
+    returns the underlying Node that it wraps, which is a bit of
+    architectural dependence that we might need to break or modify in the
+    future in response to additional requirements.
     """
     try:
         get = obj.get
@@ -64,34 +64,35 @@ def node_conv(obj):
     return result
 
 class _PathList:
-    """An actual PathList object."""
+    """An actual PathList object.
 
-    def __init__(self, pathlist, split=True) -> None:
-        """
-        Initializes a PathList object, canonicalizing the input and
-        pre-processing it for quicker substitution later.
+    Initializes a :class:`PathList` object, canonicalizing the input and
+    pre-processing it for quicker substitution later.
 
-        The stored representation of the PathList is a list of tuples
-        containing (type, value), where the "type" is one of the TYPE_*
-        variables defined above.  We distinguish between:
+    The stored representation of the :class:`PathList` is a list of tuples
+    containing (type, value), where the "type" is one of the ``TYPE_*``
+    variables defined above.  We distinguish between:
 
-            strings that contain no '$' and therefore need no
-            delayed-evaluation string substitution (we expect that there
-            will be many of these and that we therefore get a pretty
-            big win from avoiding string substitution)
+    *   Strings that contain no ``$`` and therefore need no
+        delayed-evaluation string substitution (we expect that there
+        will be many of these and that we therefore get a pretty
+        big win from avoiding string substitution)
 
-            strings that contain '$' and therefore need substitution
-            (the hard case is things like '${TARGET.dir}/include',
-            which require re-evaluation for every target + source)
+    *   Strings that contain ``$`` and therefore need substitution
+        (the hard case is things like ``${TARGET.dir}/include``,
+        which require re-evaluation for every target + source)
 
-            other objects (which may be something like an EntryProxy
-            that needs a method called to return a Node)
+    *   Other objects (which may be something like an
+        :class:`~SCons.Node.FS.EntryProxy`
+        that needs a method called to return a Node)
 
-        Pre-identifying the type of each element in the PathList up-front
-        and storing the type in the list of tuples is intended to reduce
-        the amount of calculation when we actually do the substitution
-        over and over for each target.
-        """
+    Pre-identifying the type of each element in the :class:`PathList`
+    up-front and storing the type in the list of tuples is intended to
+    reduce the amount of calculation when we actually do the substitution
+    over and over for each target.
+    """
+
+    def __init__(self, pathlist, split=True) -> None:
         if SCons.Util.is_String(pathlist):
             if split:
                 pathlist = pathlist.split(os.pathsep)
@@ -152,34 +153,33 @@ class PathListCache:
     use the same Memoizer pattern that we use elsewhere to count cache
     hits and misses, which is very valuable.
 
-    Lookup keys in the cache are computed by the _PathList_key() method.
+    Lookup keys in the cache are computed by the :meth:`_PathList_key` method.
     Cache lookup should be quick, so we don't spend cycles canonicalizing
-    all forms of the same lookup key.  For example, 'x:y' and ['x',
-    'y'] logically represent the same list, but we don't bother to
+    all forms of the same lookup key.  For example, ``x:y`` and ``['x', 'y']``
+    logically represent the same list, but we don't bother to
     split string representations and treat those two equivalently.
     (Note, however, that we do, treat lists and tuples the same.)
 
     The main type of duplication we're trying to catch will come from
     looking up the same path list from two different clones of the
-    same construction environment.  That is, given
+    same construction environment.  That is, given::
 
         env2 = env1.Clone()
 
-    both env1 and env2 will have the same CPPPATH value, and we can
-    cheaply avoid re-parsing both values of CPPPATH by using the
+    both ``env1`` and ``env2`` will have the same ``CPPPATH`` value, and we can
+    cheaply avoid re-parsing both values of ``CPPPATH`` by using the
     common value from this cache.
     """
     def __init__(self) -> None:
         self._memo = {}
 
     def _PathList_key(self, pathlist):
-        """
-        Returns the key for memoization of PathLists.
+        """Returns the key for memoization of PathLists.
 
         Note that we want this to be pretty quick, so we don't completely
         canonicalize all forms of the same list.  For example,
-        'dir1:$ROOT/dir2' and ['$ROOT/dir1', 'dir'] may logically
-        represent the same list if you're executing from $ROOT, but
+        ``dir1:$ROOT/dir2`` and ``['$ROOT/dir1', 'dir']`` may logically
+        represent the same list if you're executing from ``$ROOT``, but
         we're not going to bother splitting strings into path elements,
         or massaging strings into Nodes, to identify that equivalence.
         We just want to eliminate obvious redundancy from the normal
@@ -191,9 +191,10 @@ def _PathList_key(self, pathlist):
 
     @SCons.Memoize.CountDictCall(_PathList_key)
     def PathList(self, pathlist, split=True):
-        """
-        Returns the cached _PathList object for the specified pathlist,
-        creating and caching a new object as necessary.
+        """Entry point for getting PathLists.
+
+        Returns the cached :class:`_PathList` object for the specified
+        pathlist, creating and caching a new object as necessary.
         """
         pathlist = self._PathList_key(pathlist)
         try:
@@ -215,7 +216,8 @@ def PathList(self, pathlist, split=True):
 
 PathList = PathListCache().PathList
 
-
+# TODO: removing the class object here means Sphinx doesn't pick up its
+#   docstrings: they're fine for reading here, but are not in API Docs.
 del PathListCache
 
 # Local Variables:

diff --git a/doc/sphinx/SCons.Node.rst b/doc/sphinx/SCons.Node.rst
@@ -1,6 +1,15 @@
 SCons.Node package
 ==================
 
+Module contents
+---------------
+
+.. automodule:: SCons.Node
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Submodules
 ----------
 
@@ -27,12 +36,3 @@ SCons.Node.Python module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: SCons.Node
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/doc/sphinx/SCons.Platform.rst b/doc/sphinx/SCons.Platform.rst
@@ -1,6 +1,15 @@
 SCons.Platform package
 ======================
 
+Module contents
+---------------
+
+.. automodule:: SCons.Platform
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Submodules
 ----------
 
@@ -91,12 +100,3 @@ SCons.Platform.win32 module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: SCons.Platform
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/doc/sphinx/SCons.Scanner.rst b/doc/sphinx/SCons.Scanner.rst
@@ -1,6 +1,15 @@
 SCons.Scanner package
 =====================
 
+Module contents
+---------------
+
+.. automodule:: SCons.Scanner
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Submodules
 ----------
 
@@ -83,12 +92,3 @@ SCons.Scanner.SWIG module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: SCons.Scanner
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/doc/sphinx/SCons.Script.rst b/doc/sphinx/SCons.Script.rst
@@ -1,6 +1,15 @@
 SCons.Script package
 ====================
 
+Module contents
+---------------
+
+.. automodule:: SCons.Script
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Submodules
 ----------
 
@@ -35,12 +44,3 @@ SCons.Script.SConscript module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: SCons.Script
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/doc/sphinx/SCons.Taskmaster.rst b/doc/sphinx/SCons.Taskmaster.rst
@@ -1,6 +1,15 @@
 SCons.Taskmaster package
 ========================
 
+Module contents
+---------------
+
+.. automodule:: SCons.Taskmaster
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Submodules
 ----------
 
@@ -11,11 +20,3 @@ SCons.Taskmaster.Job module
     :members:
     :undoc-members:
     :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: SCons.Taskmaster
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/doc/sphinx/SCons.Util.rst b/doc/sphinx/SCons.Util.rst
@@ -1,34 +1,53 @@
 SCons.Util package
 ==================
 
-Submodules
-----------
+Module contents
+---------------
 
 .. automodule:: SCons.Util
     :members:
     :undoc-members:
     :show-inheritance:
 
+
+Submodules
+----------
+
+SCons.Util.envs module
+----------------------
+
 .. automodule:: SCons.Util.envs
     :members:
     :undoc-members:
     :show-inheritance:
 
+SCons.Util.filelock module
+--------------------------
+
 .. automodule:: SCons.Util.filelock
     :members:
     :undoc-members:
     :show-inheritance:
 
+SCons.Util.hashes module
+------------------------
+
 .. automodule:: SCons.Util.hashes
     :members:
     :undoc-members:
     :show-inheritance:
 
+SCons.Util.sctypes module
+-------------------------
+
 .. automodule:: SCons.Util.sctypes
     :members:
     :undoc-members:
     :show-inheritance:
 
+SCons.Util.stats module
+-----------------------
+
 .. automodule:: SCons.Util.stats
     :members:
     :undoc-members: