Merge pull request #4716 from mwichmann/doc/expand-sphinx

Tweak the API Docs build (Sphinx) configuration  [skip appveyor]

Author: bdbaddog

CHANGES.txt

@@ -40,6 +40,12 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       one from PEP 308 introduced in Python 2.5 (2006). The idiom being
       replaced (using and/or) is regarded as error prone.
     - Improve the description of PackageVariable.
+    - Tweak the "API Docs" build (Sphinx) configuration a bit. Some
+      one-file modules were reported as duplicated, this is fixed.
+      SConsDoc and SConsExample are now included - their API is
+      interesting to developers working on SCons (needed to write docs),
+      even if not part of "The SCons API" itself.
+      Reworded the API Docs intro sectios a bit.
 
 
 RELEASE 4.9.1 -  Thu, 27 Mar 2025 11:40:20 -0700

RELEASE.txt

@@ -64,6 +64,11 @@ DOCUMENTATION
 
 - Improve the description of PackageVariable.
 
+- The "API Docs" build (Sphinx) configuration is improved, and
+  SConsDoc and SConsExample are now included - their API is
+  interesting to developers working on SCons (needed to write docs),
+  even if not part of "The SCons API" itself.
+
 DEVELOPMENT
 -----------
 

doc/sphinx/SCons.rst

@@ -9,21 +9,6 @@ Module contents
     :undoc-members:
     :show-inheritance:
 
-Subpackages
------------
-
-.. toctree::
-
-    SCons.Node
-    SCons.Platform
-    SCons.Scanner
-    SCons.Script
-    SCons.Taskmaster
-    SCons.Tool
-    SCons.Util
-    SCons.Variables
-    SCons.compat
-
 Submodules
 ----------
 
@@ -174,3 +159,27 @@ SCons.exitfuncs module
     :members:
     :undoc-members:
     :show-inheritance:
+
+SConsDoc documentation module
+-----------------------------
+
+This module is NOT part of the SCons build tool itself.
+It is supporting tooling, invoked by tools used to build
+documentation components.
+
+.. automodule:: bin.SConsDoc
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+SConsExamples documentation module
+----------------------------------
+
+This module is NOT part of the SCons build tool itself.
+It is supporting tooling, invoked by tools used to build
+documentation components.
+
+.. automodule:: bin.SConsExamples
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/sphinx/conf.py

@@ -18,6 +18,9 @@
 #
 import os
 import sys
+
+sys.path.insert(0, os.path.abspath('../../testing/framework'))
+sys.path.insert(0, os.path.abspath('../../bin'))
 sys.path.insert(0, os.path.abspath('../../'))
 
 # -- General configuration ------------------------------------------------

doc/sphinx/index.rst

@@ -1,44 +1,49 @@
-.. SCons documentation master file, originally created by
-   sphinx-quickstart on Mon Apr 30 09:36:53 2018.
+.. SCons documentation master file, originally created by sphinx-quickstart on Mon Apr 30 09:36:53 2018.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
 SCons API Documentation
 =======================
 
 .. Attention::
-   This is the **internal** API Documentation for SCons (aka
-   "everything"). It is generated automatically from code docstrings using
-   the `Sphinx <https://www.sphinx-doc.org>`_ documentation generator.
 
-   Any missing/incomplete information is due to shortcomings in the
-   docstrings in the code. To not be too flippant about it, filling
-   in all the docstrings has not always been a priority across the
-   two-plus decades SCons has been in existence (contributions on this
-   front are welcomed).  Additionally, for SCons classes which inherit
-   from Python standard library classes (such as ``UserList``,
-   ``UserDict``, ``UserString``), the generated pages will show methods
-   that are inherited, sometimes with no information at all, sometimes
-   with a signature/description that seems mangled: Python upstream has
-   similar limitations as to the quality of dosctrings vs the current
-   standards Sphinx expects.  Inherited interfaces from outside SCons
-   code can be identified by the lack of a ``[source]`` button to the
-   right of the method signature.
-
-   If you are looking for the Public API - the interfaces that have
+   This is the **internal** API Documentation for SCons.
+   It is generated automatically from code docstrings using
+   the `Sphinx <https://www.sphinx-doc.org>`_ documentation generator,
+   and covers much more than the Public API.
+   If you were looking for the Public API - the interfaces that have
    long-term consistency guarantees, which you can reliably use when
    writing a build system for a project - see the `SCons Reference Manual
    <https://scons.org/doc/production/HTML/scons-man.html>`_.  Note that
-   what is Public API and what is not is not clearly delineated in these
-   API Docs.
+   what is Public API and what is not is often not clearly delineated in
+   these API Docs.
 
-   The target audience is both developers contributing to SCons itself,
+   The target audience is developers contributing to SCons itself,
    and those writing external Tools, Builders, and other related
    functionality for their project, who may need to reach beyond the
    Public API to accomplish their tasks. Reaching into internals is fine,
    but comes with the usual risks of "things here could change, it's up
    to you to keep your code working".
 
+   Any missing/incomplete information is due to shortcomings in the
+   docstrings in the code. Without being flippant, filling
+   in all the docstrings has not always been a priority across the
+   two-plus decades SCons has been in existence. Contributions
+   improving the docstring front are welcome. It is often useful when
+   making some larger change to fill in docstrings and suitable
+   type annotations in the code being modified, "leaving the world
+   a better place", as it were.
+
+   Note that the Sphinx configuration is limited, still a work
+   in progress.  SCons classes which inherit from Python standard
+   library classes (e.g. ``UserList``, ``UserDict``, ``UserString``),
+   may be allowed to show inherited mmembers; the Python standard library
+   occasionally has little to no helpful docstring information.
+   Inherited interfaces from outside SCons code can be identified by the
+   lack of a ``[source]`` button to the right of the method signature.
+   Such classes should be evaluated case-by-case and possibly
+   switched to not show inherited members, depending on which way
+   seems to provide the more useful result.
 
 .. toctree::
    :maxdepth: 2
@@ -55,7 +60,6 @@ SCons API Documentation
    SCons.Util
    SCons.Variables
 
-
 Indices and Tables
 ==================