Improve docstrings for abstract hardware objects

General improvements to the docstrings of abstract hardware objects:

* Add an `Emits` custom section for Sphinx's Napoleon extension
* Fix docstrings formatting
* Document some emitted signals
* Move types from docstring to type hints when possible
* Som formatting with `black`

GitHub: supersedes #866
GitHub: supersedes #947

docs/conf.py

@@ -86,6 +86,10 @@
 
 extensions.append("sphinx.ext.napoleon")
 
+napoleon_custom_sections = [
+    ("Emits", "params_style"),
+]
+
 napoleon_numpy_docstring = False
 
 
@@ -99,7 +103,11 @@
 
 extensions.append("myst_parser")
 
-myst_enable_extensions = ("fieldlist",)
+myst_enable_extensions = (
+    "attrs_block",
+    "colon_fence",
+    "fieldlist",
+)
 
 
 # -- Options for sphinxcontrib.mermaid

docs/source/dev/docs.md

@@ -84,6 +84,27 @@ extension is enabled to handle docstrings within the Python code
 and it is configured for
 [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).
 
+#### Custom sections for docstrings
+
+A
+[custom section](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_custom_sections)
+title for docstrings is available to document *hardware objects*:
+
+* `Emits` for signals emitted by *hardware objects*
+
+It can be used like in this example:
+
+```python
+class Thing(HardwareObject):
+    """Some thing.
+
+    Emits:
+        isReady (bool):
+            Emitted when the readiness state changes.
+    """
+```
+
+
 ### Diagrams
 
 The