Initial ocumentation for core events, refs #2240

datasette/events.py

@@ -19,16 +19,38 @@ def properties(self):
 
 @dataclass
 class LoginEvent(Event):
+    """
+    Event name: ``login``
+
+    A user (represented by ``event.actor``) has logged in.
+    """
     name = "login"
 
 
 @dataclass
 class LogoutEvent(Event):
+    """
+    Event name: ``logout``
+
+    A user (represented by ``event.actor``) has logged out.
+    """
     name = "logout"
 
 
 @dataclass
 class CreateTableEvent(Event):
+    """
+    Event name: ``create-table``
+
+    A new table has been created in the database.
+
+    :ivar database: The name of the database where the table was created.
+    :type database: str
+    :ivar table: The name of the table that was created
+    :type table: str
+    :ivar schema: The SQL schema definition for the new table.
+    :type schema: str
+    """
     name = "create-table"
     database: str
     table: str

docs/conf.py

@@ -40,6 +40,8 @@
 if not os.environ.get("DISABLE_SPHINX_INLINE_TABS"):
     extensions += ["sphinx_inline_tabs"]
 
+autodoc_member_order = "bysource"
+
 extlinks = {
     "issue": ("https://github.com/simonw/datasette/issues/%s", "#%s"),
 }

docs/events.rst

@@ -0,0 +1,12 @@
+Events
+======
+
+Datasette includes a mechanism for tracking events that occur while the software is running. This is primarily intended to be used by plugins, which can both trigger events and listen for events.
+
+The core Datasette application triggers events when certain things happen. This page describes those events.
+
+Plugins can listen for events using the :ref:`plugin_hook_track_event` plugin hook.
+
+.. automodule:: datasette.events
+    :members:
+    :exclude-members: Event

docs/index.rst

@@ -63,5 +63,6 @@ Contents
    plugin_hooks
    testing_plugins
    internals
+   events
    contributing
    changelog