Fix sphinx-build warnings and turn warnings into errors (#942)

Fix the 100+ warnings when generating docs (and make warnings errors)

- Hack-fix issue with hyphenated names in TypedDict fields
- Ignore several private classes in Sphinx config's nitpick_ignore list
- Make several things public as they're used in public methods:
  * Serializable protocol
  * Pebble plan/layer TypesDicts (and sub-dicts), as people do build
    those in Python
- Remove TypedDicts for charm metadata (it's not useful, as users
  don't build their charm metadata in Python; it's in YAML). 
- Remove TypedDicts for event snapshots, as IMO these don't add
  enough value to pay for themselves.
- Replace some named types with spelled-out types for clarity, eg:
  _SerializedData is just Dict[str, Any]; Numerical is just Union[int, float].
- Use simpler Dict[str, Any] rather than _JsonObject (the more complex,
  "exact" type doesn't pay for itself).
- Change EventSource and BoundEvent to non-generic classes to simplify.

Part of: #920

.readthedocs.yaml

@@ -10,4 +10,5 @@ build:
     python: "3.11"
 
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py
+  fail_on_warning: true

docs/conf.py

@@ -31,6 +31,20 @@ def _compute_navigation_tree(context):
 furo._compute_navigation_tree = _compute_navigation_tree
 
 
+# Pull in fix from https://github.com/sphinx-doc/sphinx/pull/11222/files to fix
+# "invalid signature for autoattribute ('ops.pebble::ServiceDict.backoff-delay')"
+import re
+import sphinx.ext.autodoc
+sphinx.ext.autodoc.py_ext_sig_re = re.compile(
+    r'''^ ([\w.]+::)?            # explicit module name
+          ([\w.]+\.)?            # module and/or class name(s)
+          ([^.()]+)  \s*         # thing name
+          (?: \((.*)\)           # optional: arguments
+           (?:\s* -> \s* (.*))?  #           return annotation
+          )? $                   # and nothing more
+          ''', re.VERBOSE)
+
+
 # -- Project information -----------------------------------------------------
 
 project = 'The Operator Framework'
@@ -59,12 +73,30 @@ def _compute_navigation_tree(context):
 # domain name if present. Example entries would be ('py:func', 'int') or
 # ('envvar', 'LD_LIBRARY_PATH').
 nitpick_ignore = [
-    ('py:class', 'TextIO'),  # typing.TextIO confuses the nitpicker
-    ('py:class', 'method'),  # types.Method confuses the nitpicker
-    ('py:class', '_ModelBackend'),  # private
-    ('py:class', '_ModelCache'), # private
-    ('py:class', 'ipaddress.ip_address'), # fake (AFAIK there is no ABC)
-    ('py:class', 'ipaddress.ip_network'), # ditto
+    ('py:class', '_AddressDict'),
+    ('py:class', '_ChangeDict'),
+    ('py:class', '_CheckInfoDict'),
+    ('py:class', '_FileInfoDict'),
+    ('py:class', '_IOSource'),
+    ('py:class', '_NetworkDict'),
+    ('py:class', '_ProgressDict'),
+    ('py:class', '_Readable'),
+    ('py:class', '_RelationMetaDict'),
+    ('py:class', '_ResourceMetaDict'),
+    ('py:class', '_ServiceInfoDict'),
+    ('py:class', '_StorageMetaDict'),
+    ('py:class', '_SystemInfoDict'),
+    ('py:class', '_TaskDict'),
+    ('py:class', '_TextOrBinaryIO'),
+    ('py:class', '_WarningDict'),
+    ('py:class', '_WebSocket'),
+    ('py:class', '_Writeable'),
+    ('py:class', 'ops.model._ModelBackend'),
+    ('py:class', 'ops.model._ModelCache'),
+    ('py:class', 'ops.storage.JujuStorage'),
+    ('py:class', 'ops.storage.SQLiteStorage'),
+    ('py:class', 'ops.testing.CharmType'),
+    ('py:obj', 'ops.testing.CharmType'),
 ]
 
 # Add any Sphinx extension module names here, as strings. They can be

ops/__init__.py

@@ -105,6 +105,7 @@
     'ObjectEvents',
     'PreCommitEvent',
     'PrefixedEvents',
+    'Serializable',
     'StoredDict',
     'StoredList',
     'StoredSet',
@@ -174,7 +175,7 @@
 # This allows "import ops; ops.main(Charm)" to work as expected.
 from . import main  # type: ignore # noqa: F401
 
-# Explicitly import names from sub-modules so users can just "import ops" and
+# Explicitly import names from submodules so users can just "import ops" and
 # then use them as "ops.X".
 from .charm import (  # noqa: F401
     ActionEvent,
@@ -236,6 +237,7 @@
     ObjectEvents,
     PreCommitEvent,
     PrefixedEvents,
+    Serializable,
     StoredDict,
     StoredList,
     StoredSet,