From a52da079d0e6cd264b052683f4bfac06ac560ff3 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 18 Aug 2022 09:25:18 -0600 Subject: 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 --- doc/sphinx/SCons.rst | 2 ++ doc/sphinx/conf.py | 26 +++++++++++++++++++++----- doc/sphinx/index.rst | 30 ++++++++++++++++++------------ 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 `_ 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 + `_. .. toctree:: :maxdepth: 2 -- cgit v0.12 From 6839654834e8206e0859c52096dc9ff9569df355 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 18 Aug 2022 09:35:53 -0600 Subject: Update docstrings in Errors module Try and get the generated apidoc a little more readable. Signed-off-by: Mats Wichmann --- SCons/Errors.py | 77 +++++++++++++++++++++++++-------------------------------- 1 file changed, 33 insertions(+), 44 deletions(-) diff --git a/SCons/Errors.py b/SCons/Errors.py index 04cea38..d37cb6d 100644 --- a/SCons/Errors.py +++ b/SCons/Errors.py @@ -24,60 +24,49 @@ """SCons exception classes. Used to handle internal and user errors in SCons. - """ import shutil import SCons.Util +# Note that not all Errors are defined here, some are at the point of use + class BuildError(Exception): """SCons Errors that can occur while building. - Attributes: - Information about the cause of the build error : - - errstr: a description of the error message - - status: the return code of the action that caused the build error. - Must be set to a non-zero value even if the build error is not due - to an action returning a non-zero returned code. - - exitstatus: SCons exit status due to this build error. - Must be nonzero unless due to an explicit Exit() - call. Not always the same as status, since - actions return a status code that should be - respected, but SCons typically exits with 2 - irrespective of the return value of the failed - action. - - filename: The name of the file or directory that caused the - build error. Set to None if no files are associated with - this error. This might be different from the target - being built. For example, failure to create the - directory in which the target file will appear. It - can be None if the error is not due to a particular - filename. + A :class:`BuildError` exception contains information both + about the erorr itself, and what caused the error. - exc_info: Info about exception that caused the build - error. Set to (None, None, None) if this build - error is not due to an exception. - - Information about the what caused the build error : - - node: the error occurred while building this target node(s) - - executor: the executor that caused the build to fail (might - be None if the build failures is not due to the - executor failing) - - action: the action that caused the build to fail (might be - None if the build failures is not due to the an - action failure) - - command: the command line for the action that caused the - build to fail (might be None if the build failures - is not due to the an action failure) + Attributes: + node: (*cause*) the error occurred while building this target node(s) + errstr: (*info*) a description of the error message + status: (*info*) the return code of the action that caused the build error. + Must be set to a non-zero value even if the build error is not due + to an action returning a non-zero returned code. + exitstatus: (*info*) SCons exit status due to this build error. + Must be nonzero unless due to an explicit :meth:`Exit` call. + Not always the same as ``status``, since actions return a status + code that should be respected, but SCons typically exits with 2 + irrespective of the return value of the failed action. + filename: (*info*) The name of the file or directory that caused the + build error. Set to ``None`` if no files are associated with + this error. This might be different from the target + being built. For example, failure to create the + directory in which the target file will appear. It + can be ``None`` if the error is not due to a particular + filename. + executor: (*cause*) the executor that caused the build to fail (might + be ``None`` if the build failures is not due to the executor failing) + action: (*cause*) the action that caused the build to fail (might be + ``None`` if the build failures is not due to the an + action failure) + command: (*cause*) the command line for the action that caused the + build to fail (might be ``None`` if the build failures + is not due to the an action failure) + exc_info: (*info*) Info about exception that caused the build + error. Set to ``(None, None, None)`` if this build + error is not due to an exception. """ -- cgit v0.12 From 146dc39ded8c7d18776f570245c62f8ac9d76f05 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 18 Aug 2022 09:42:34 -0600 Subject: Temparily switch theme in GH Action [skip appveyor] Signed-off-by: Mats Wichmann --- .github/workflows/scons-package.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/scons-package.yml b/.github/workflows/scons-package.yml index 91acecb..ff71862 100644 --- a/.github/workflows/scons-package.yml +++ b/.github/workflows/scons-package.yml @@ -24,6 +24,8 @@ jobs: python -m pip install --upgrade pip setuptools wheel #python -m pip install flake8 pytest if [ -f requirements-pkg.txt ]; then pip install -r requirements-pkg.txt; elif [ -f requirements.txt ]; then pip install -r requirements.txt; fi + #XXX if we keep this, merge into requirements-pkg.txt + pip install sphinx-book-theme sudo apt-get update sudo apt-get -y install docbook-xml docbook-xsl xsltproc fop docbook-xsl-doc-pdf # try to keep the texlive install as small as we can to save some time/space -- cgit v0.12 From 469619347ca50278b045ff84753c06925d067572 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 18 Aug 2022 12:02:48 -0600 Subject: sider: fix typo in comment in sphinx config [skip appveyor] Signed-off-by: Mats Wichmann --- doc/sphinx/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 8ffecd1..7f304e0 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -60,7 +60,7 @@ 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_include_special_with_doc = True # not default napoleon_use_admonition_for_examples = True # not default napoleon_use_admonition_for_notes = False napoleon_use_admonition_for_references = False -- cgit v0.12 From 6884a878e930c867f3946a38e3da2e930e2f2c8b Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 21 Aug 2022 06:56:41 -0600 Subject: Promote sphinx-book-theme to preferred [skip appveyor] This will now be used for the API docs build. Signed-off-by: Mats Wichmann --- .github/workflows/scons-package.yml | 2 -- requirements-pkg.txt | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/scons-package.yml b/.github/workflows/scons-package.yml index ff71862..91acecb 100644 --- a/.github/workflows/scons-package.yml +++ b/.github/workflows/scons-package.yml @@ -24,8 +24,6 @@ jobs: python -m pip install --upgrade pip setuptools wheel #python -m pip install flake8 pytest if [ -f requirements-pkg.txt ]; then pip install -r requirements-pkg.txt; elif [ -f requirements.txt ]; then pip install -r requirements.txt; fi - #XXX if we keep this, merge into requirements-pkg.txt - pip install sphinx-book-theme sudo apt-get update sudo apt-get -y install docbook-xml docbook-xsl xsltproc fop docbook-xsl-doc-pdf # try to keep the texlive install as small as we can to save some time/space diff --git a/requirements-pkg.txt b/requirements-pkg.txt index 3c2c385..10b5393 100644 --- a/requirements-pkg.txt +++ b/requirements-pkg.txt @@ -9,5 +9,5 @@ readme-renderer # sphinx pinned because it has broken several times on new releases sphinx>=5.1.1 -sphinx_rtd_theme +sphinx-book-theme rst2pdf -- cgit v0.12 From f1f36b69ce5594b0e5a6d56b731a4df4e2ae5321 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 21 Aug 2022 07:46:36 -0600 Subject: Needed to turn off sphinx-rtd-theme another place [skip appveyor] Signed-off-by: Mats Wichmann --- doc/sphinx/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 7f304e0..5ad5448 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -38,7 +38,7 @@ extensions = [ 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.viewcode', - 'sphinx_rtd_theme', + #'sphinx_rtd_theme', 'rst2pdf.pdfbuilder', ] -- cgit v0.12