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 -----------------