Integrate new & revised docstrings in spyder.api.widgets module

[CAM-Gerlach]

Pull Request

Pull Request Checklist

• Read and followed this repo's Contributing Guidelines
• Based your PR on the latest version of the correct branch
• Checked your code and writing carefully
• Described your changes and the motivation for them below

Description of Changes

Requires spyder-ide/spyder#25598

• Thoroughly revise the docstring content for the spyder.api.widgets modules:
  • Ensure all modules and APIs have a proper summary line
  • Document un(der) documented public APIs
  • Greatly clarify and expand existing descriptions
  • Add all param, return and attribute types to both signatures and docstrings
  • Fix and clarify many instances of missing, incorrect or unclear param types in the signature and docstrings related to parameters accepting None and/or having a default value, and clarify in the docstring what that value is and its meaning.
  • Add and fix Sphinx roles and directives throughout
  • Fix all Sphinx broken references in the affected modules
• Document several other API issues across the touched modules:
  • Add pending deprecation of ToolbarStyle and SpyderMenuProxyStyle and replacement with the corresponding private names, as they were never intended to be used publicly
  • Document not specifying a known TYPE for ToolbarStyle raise a SpyderAPIError rather than silently not working as intended
  • Add admonition in SpyderToolbar to not use it directly in favor of its subclasses ApplicationToolbar and MainWidgetToolbar
  • Document removal of options arg from SpyderActionMixin.update_actions() mixin, which is inconsistent and incompatible with all its actual implementations and already will raise an error at runtime

[netlify]

❌ Deploy Preview for spyder-api-docs-preview failed.

Name	Link
🔨 Latest commit	5603428
🔍 Latest deploy log	https://app.netlify.com/projects/spyder-api-docs-preview/deploys/6983dc3b54170e000801c69b

[ccordoba12]

Thanks @CAM-Gerlach!