merge with stable

1 files changed, 12 insertions, 1 deletions

diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index 48f5d96e..4edab5db 100644
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -382,7 +382,18 @@ Sphinx core events
 ------------------
 
 These events are known to the core.  The arguments shown are given to the
-registered event handlers.
+registered event handlers.  Use :meth:`.connect` in an extension's ``setup``
+function (note that ``conf.py`` can also have a ``setup`` function) to connect
+handlers to the events.  Example:
+
+.. code-block:: python
+
+   def source_read_handler(app, docname, source):
+       print('do something here...')
+
+   def setup(app):
+       app.connect('source-read', source_read_handler)
+
 
 .. event:: builder-inited (app)