Merge pull request spyder-ide#14 from CAM-Gerlach/revise-top-level-docstrings

Revise docstrings for modules, fix ref errors, hide private modules & add env var

Author: ccordoba12

docs/_templates/custom-module-template.rst

@@ -55,7 +55,8 @@
    :template: custom-module-template.rst
    :recursive:
 {% for item in modules %}
-   {% if not 'tests' in item %}
+   {%- set item_fullname %}{{ fullname }}.{{ item }}{% endset %}
+   {%- if not (ignore_module_pattern in item or item_fullname in ignore_modules) %}
        {{ item }}
    {%- endif %}
 {%- endfor %}

docs/conf.py

@@ -17,6 +17,7 @@
 
 # Standard library imports
 import datetime
+import os
 import sys
 from pathlib import Path
 
@@ -36,7 +37,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = "5"
+needs_sphinx = "6.2"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones.
@@ -102,9 +103,37 @@
 # pylint: disable-next = consider-using-namedtuple-or-dataclass
 intersphinx_mapping = {
     "python": ("https://docs.python.org/", None),
+    "PyQt5": ("https://www.riverbankcomputing.com/static/Docs/PyQt5/", None),
     "spyder": ("https://docs.spyder-ide.org/current/", None),
 }
 
+# Warning suppression
+suppress_warnings = []
+
+# Nitpick warning ignore list
+nitpick_ignore_regex = {
+    # Spyder modules currently not included in the build
+    (
+        "py:.+",
+        # pylint: disable-next = line-too-long
+        "spyder.(app|config|fonts|images|locale|plugins|tests|utils|widgets|windows).*",  # noqa: E501
+    ),
+    # Numpydoc optional
+    ("py:class", "optional"),
+    # Typing params
+    ("py:.+", ".*_P"),
+    ("py:.+", ".*_RT"),
+    ("py:.+", ".*_T"),
+    # Cannot use type aliases to fix refs inside type aliases or class bases
+    ("py:class", "asyncio.events.AbstractEventLoop"),
+    ("py:class", "concurrent.futures._base.Future"),
+    # Type aliases don't work properly in Sphinx <9
+    ("py:class", "LoopID"),
+    ("py:class", "OptionSet"),
+    ("py:class", "spyder.api.preferences.OptionSet"),
+}
+
+
 # -- Options for HTML output -------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -134,9 +163,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-# Warning suppression
-suppress_warnings = []
-
 
 # -- Options for HTMLHelp output ---------------------------------------
 
@@ -246,6 +272,9 @@
 # Default flags used by autodoc directives
 autodoc_default_options = {
     "members": True,
+    "private-members": "_",
+    "special-members": True,
+    "exclude-members": "__weakref__",
     "show-inheritance": True,
 }
 
@@ -256,14 +285,49 @@
     # "qstylizer",
 ]
 
+# Configure type aliases for signatures
+autodoc_type_aliases = {
+    # Actual type aliases
+    "LoopID": "spyder.api.asyncdispatcher.LoopID",
+    "OptionSet": "spyder.api.preferences.OptionSet",
+    # Ref name aliases
+    "AbstractEventLoop": "asyncio.AbstractEventLoop",
+    "asyncio.AbstractEventLoop": "asyncio.AbstractEventLoop",
+    "asyncio.events.AbstractEventLoop": "asyncio.AbstractEventLoop",
+    "Future": "concurrent.futures.Future",
+    "concurrent.futures.Future": "concurrent.futures.Future",
+    "concurrent.futures._base.Future": "concurrent.futures.Future",
+}
+
+# Monkeypatch to fix type aliases not working in classmethods with Sphinx
+# See sphinx-doc/sphinx#10333
+# pylint: disable-next = wrong-import-position
+from sphinx.util import inspect  # noqa: E402
+
+inspect.TypeAliasForwardRef.__repr__ = lambda self: self.name
+inspect.TypeAliasForwardRef.__hash__ = lambda self: hash(self.name)
+
+# Set list of modules and patterns to ignore in the autosummary template
+autosummary_context = {
+    "ignore_module_pattern": "tests",
+    "ignore_modules": [
+        "spyder.api.editor",
+        "spyder.api.plugins.enum",
+        "spyder.api.plugins.new_api",
+        "spyder.api.plugins.tests",
+    ],
+}
+
 # Generate autosummaries if the autodoc tag is passed
 # pylint: disable-next = undefined-variable
 if "autodoc" in tags:  # noqa: F821
     autosummary_generate = True
+    os.environ["SPHINX_AUTODOC"] = "1"
+    extensions.append("sphinx_qt_documentation")  # Errors out w/o Qt installed
 else:
     autosummary_generate = False
-    suppress_warnings += ["autodoc", "autosummary", "toc.excluded"]
     exclude_patterns += ["reference.rst"]
+    suppress_warnings += ["autodoc", "autosummary", "toc.excluded"]
 
 
 # -- Additional Directives ---------------------------------------------------

requirements.txt

@@ -1,3 +1,4 @@
 myst-parser>=1,<5  # Docs markup; cap to support wide range of py versions
-sphinx>=5,<9  # Docs generator; cap to range confirmed supported by deps
+sphinx>=6.2,<9  # Docs generator; cap to range confirmed supported by deps
 sphinx-book-theme>=1,<2  # Docs theme; cap to support wide range of py versions
+sphinx-qt-documentation>=0.4.1,<1  # Crossrefs to Qt documentation