From 53fccd877c0af72669747990ca51597f01ea2aed Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 16 May 2024 10:44:52 -0600 Subject: [PATCH] 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 --- CHANGES.txt | 4 ++ RELEASE.txt | 2 + SCons/Debug.py | 6 +-- SCons/PathList.py | 84 +++++++++++++++++++++-------------------- doc/sphinx/SCons.Node.rst | 18 ++++----- doc/sphinx/SCons.Platform.rst | 18 ++++----- doc/sphinx/SCons.Scanner.rst | 18 ++++----- doc/sphinx/SCons.Script.rst | 18 ++++----- doc/sphinx/SCons.Taskmaster.rst | 17 +++++---- doc/sphinx/SCons.Util.rst | 23 ++++++++++- doc/sphinx/SCons.Variables.rst | 17 +++++---- 11 files changed, 127 insertions(+), 98 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 61ce2dfe8..8815a2061 100644 --- 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 index bea3c9f5a..614333986 100644 --- 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 index 9397fdeda..9a6433ee8 100644 --- 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 index 33ac7e58b..fcda3c59a 100644 --- 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 @@ class PathListCache: @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 @@ class PathListCache: 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 index b6d5c8f0f..a4b79677d 100644 --- 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 index 8a5574495..d1a0b8864 100644 --- 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 index 484bd4312..b4d264c7a 100644 --- 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 index 704b8faaf..ef883074a 100644 --- 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 index adf90137a..9c332ca7d 100644 --- 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 index 553db7a1b..9e83db76d 100644 --- 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: diff --git a/doc/sphinx/SCons.Variables.rst b/doc/sphinx/SCons.Variables.rst index dc2388af6..089fe4e68 100644 --- a/doc/sphinx/SCons.Variables.rst +++ b/doc/sphinx/SCons.Variables.rst @@ -1,6 +1,15 @@ SCons.Variables package ======================= +Module contents +--------------- + +.. automodule:: SCons.Variables + :members: + :undoc-members: + :show-inheritance: + + Submodules ---------- @@ -44,11 +53,3 @@ SCons.Variables.PathVariable module :undoc-members: :show-inheritance: - -Module contents ---------------- - -.. automodule:: SCons.Variables - :members: - :undoc-members: - :show-inheritance: -- 2.11.4.GIT