From b8fddf9c0b1369d988596db380b8a1ad7c4a315f Mon Sep 17 00:00:00 2001
From: Ashley Whetter <ashley@awhetter.co.uk>
Date: Sat, 5 Oct 2019 15:47:03 -0700
Subject: [PATCH] Added some missing documentation

---
 CHANGELOG.rst             |  1 +
 docs/conf.py              | 26 ++++++++++++++++++++++++++
 docs/reference/config.rst | 32 +++++++++++++++++++++++++++++++-
 3 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 80d0a36..16620b3 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -12,6 +12,7 @@ Features
 * (Python) Can read per argument type comments with astroid > 2.2.5.
 * (Python) Added autoapidecorator directive with Sphinx >= 2.0.
 * (Python) Can use autodoc_docstring_signature with Autodoc-style directives.
+* (Python) Added autoapi-skip-member event.
 * Made it more clear which file causes an error, when an error occurs.
 * Sphinx language domains are now optional dependencies.
 
diff --git a/docs/conf.py b/docs/conf.py
index 9d0ddc3..8c54763 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -281,7 +281,33 @@ texinfo_documents = [
 #texinfo_no_detailmenu = False
 
 
+import re
+
+from sphinx import addnodes
+
+event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
+
+def parse_event(env, sig, signode):
+    m = event_sig_re.match(sig)
+    if not m:
+        signode += addnodes.desc_name(sig, sig)
+        return sig
+    name, args = m.groups()
+    signode += addnodes.desc_name(name, name)
+    plist = addnodes.desc_parameterlist()
+    for arg in args.split(','):
+        arg = arg.strip()
+        plist += addnodes.desc_parameter(arg, arg)
+    signode += plist
+    return name
+
+
 def setup(app):
+    from sphinx.util.docfields import TypedField
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')
+    fdesc = TypedField('parameter', label='Parameters',
+                         names=['param'], typenames=['type'], can_collapse=True)
+    app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
+                        doc_field_types=[fdesc])
diff --git a/docs/reference/config.rst b/docs/reference/config.rst
index 25aaadb..f23dcd8 100644
--- a/docs/reference/config.rst
+++ b/docs/reference/config.rst
@@ -63,7 +63,7 @@ Configuration Options
 	:doc:`directives`.
 
 
-Customization Options
+Customisation Options
 ---------------------
 
 .. confval:: autoapi_options
@@ -135,6 +135,36 @@ Customization Options
 	docstring is empty and the class defines a ``__new__`` with a docstring,
 	the ``__new__`` docstring is used instead of the ``__init__`` docstring.
 
+Events
+~~~~~~
+
+The following events allow you to control the behaviour of AutoAPI.
+
+.. event:: autoapi-skip-member (app, what, name, obj, skip, options)
+
+	(Python only)
+	Emitted when a template has to decide whether a member should be included
+	in the documentation.
+	Usually the member is skipped if a handler returns ``True``,
+	and included otherwise.
+	Handlers should return ``None`` to fall back to the default skipping
+	behaviour of AutoAPI or another attached handler.
+
+	:param app: The Sphinx application object.
+	:param what: The type of the object which the docstring belongs to.
+		This can be one of:
+		``"attribute"``, ``"class"``, ``"data"``, ``"exception"``,
+		``"function"``, ``"method"``, ``"module"``, ``"package"``.
+	:type what: str
+	:param name: The fully qualified name of the object.
+	:type name: str
+	:param obj: The object itself.
+	:type obj: PythonPythonMapper
+	:param skip: Whether AutoAPI will skip this member if the handler
+		does not override the decision.
+	:type skip: bool
+	:param options: The options given to the directive.
+
 
 Debugging Options
 -----------------