update docstrings to RST for Sphinx

docs/conf.py

@@ -15,13 +15,22 @@ author = 'Sam Griesemer'
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.viewcode",
-    "myst_parser",
+    "sphinx.ext.autosummary", # enables a directive to be specified manually that gathers
+                              # module/object summary details in a table
+    "sphinx.ext.viewcode",    # allow viewing source in the HTML pages
+    "myst_parser",            # only really applies to manual docs; docstrings still need RST-like
+    "sphinx.ext.napoleon",    # enables Google-style docstring formats
+    "sphinx_autodoc_typehints", # external extension that allows arg types to be inferred by type hints
 ]
 autosummary_generate = True
 autosummary_imported_members = True
 
+# include __init__ definitions in autodoc
+autodoc_default_options = {
+    'special-members': '__init__',
+}
+#smartquotes = True
+
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 

docs/index.md

@@ -3,19 +3,23 @@
 {ref}`modindex`
 {ref}`search`
 
+## Top-level module overview
+
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
+   :recursive:
 
     execlog.Handler
     execlog.Listener
     execlog.Router
     execlog.Server
+    execlog.listeners
 ```
 
+## Auto-reference contents
 ```{toctree}
 :maxdepth: 3
-:caption: Autoref
 
 _autoref/execlog.rst
 ```

docs/reference/documentation/sphinx.md

@@ -105,7 +105,19 @@ pages:
 **Reference directives**
 
 
+## Notes on docstring syntax
+- Code literals need to be surrounded in two backticks, e.g., "``variable``". Sphinx will
+  also complain if you make the reference plural by having an "s" after the backtick; it
+  needs to go on the inside.
+- MyST parsing, even if enabled, doesn't apply to docstrings. You need to use RST
+  generally, with a few directives being different under extensions like `napoleon`.
+- Code blocks and admonitions need a space between the heading and the rest of the
+  content.
+
+Nice syntax cheatsheet [here][4]
+
+
 [1]: https://pradyunsg.me/furo/
 [2]: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
 [3]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#
-
+[4]: https://sphinx-tutorial.readthedocs.io/cheatsheet/