Tweak the apidocs build

* Be more explicit about napoleon config, and tweak to allow
  "Attribute" to be grouped as for "Arguments" (:attr: and :param:
  in the numpy style).
* Disable inherited members for the Errors module, because the
  exception classes were picking up bits from the Python base
  Exception, which has no annotation available.
* Update the introduction.

Experimentally, try the "sphinx-book" theme (we can go back to
sphinx-rtd-theme before pushing if this is disliked).

Signed-off-by: Mats Wichmann <mats@linux.com>

3 files changed, 41 insertions, 17 deletions

diff --git a/doc/sphinx/SCons.rst b/doc/sphinx/SCons.rst
index b9959e3..c6320e7 100644
--- a/doc/sphinx/SCons.rst
+++ b/doc/sphinx/SCons.rst
@@ -83,11 +83,13 @@ SCons.Environment module
 
 SCons.Errors module
 -------------------
+.. Turn off inherited members to quiet fluff from the Python base Exception
 
 .. automodule:: SCons.Errors
     :members:
     :undoc-members:
     :show-inheritance:
+    :no-inherited-members:
 
 SCons.Executor module
 ---------------------
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index e1c72a6..8ffecd1 100644
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -46,15 +46,30 @@ autosummary_generate = True
 
 autodoc_default_options = {
     "members": True,
-    #"special-members": True,
+    "special-members": False,
     "private-members": True,
     "inherited-members": True,
     "undoc-members": True,
     "exclude-members": '__weakref__',
 }
 autodoc_exclude_members = ['*Tests']
-napoleon_include_special_with_doc = False
+
+# Napoleon settings.  Nearly all defaults, listed explicitly to be safe.
+# See: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = True
+napoleon_include_special_with_doc = True  # not defualt
+napoleon_use_admonition_for_examples = True  # not default
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = True  # not default
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -73,7 +88,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'SCons'
-copyright = '2021, SCons Project'
+copyright = '2022, SCons Project'
 author = 'SCons Project Team'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -111,7 +126,8 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+#html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -212,4 +228,4 @@ texinfo_documents = [
 # -- for PDF
 # Grouping the document tree into PDF files. List of tuples
 # (source start file, target name, title, author, options).
-pdf_documents = [('index', u'scons-api', u'SCons API Docs', u'SCons Project'),]
+pdf_documents = [('index', 'scons-api', 'SCons API Docs', 'SCons Project'),]
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 6828154..a6bbec1 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -1,19 +1,25 @@
-.. SCons documentation master file, created by
+.. 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 Project API Documentation
-===============================
-
-This is the internal API Documentation for SCons.
-The Documentation is generated using the Sphinx tool.
-The target audience is developers working on SCons itself,
-so it does not clearly delineate what is "Public API" -
-interfaces for use in your SCons configuration scripts
-which have a consistency guarantee, and what is internal,
-so always keep the SCons manual page around for helping
-with such determinations.
+SCons API Documentation
+=======================
+
+.. Attention::
+   This is the **internal** API Documentation for SCons.
+   The documentation is automatically generated for each release
+   from the source code using the
+   `Sphinx <https://www.sphinx-doc.org>`_ tool.
+   Missing information is due to shortcomings in the docstrings in the code,
+   which are by no means complete (contributions welcomed!).
+
+   The target audience is developers working on SCons itself:
+   what is "Public API" is not clearly deliniated here.
+   The interfaces available for use in SCons configuration scripts,
+   which have a consistency guarantee, are those documented in the 
+   `SCons Reference Manual
+   <https://scons.org/doc/production/HTML/scons-man.html>`_.
 
 .. toctree::
    :maxdepth: 2