diff options
Diffstat (limited to 'doc/usage/extensions/autodoc.rst')
| -rw-r--r-- | doc/usage/extensions/autodoc.rst | 853 |
1 files changed, 853 insertions, 0 deletions
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst new file mode 100644 index 0000000..1498ae9 --- /dev/null +++ b/doc/usage/extensions/autodoc.rst @@ -0,0 +1,853 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings +================================================================== + +.. module:: sphinx.ext.autodoc + :synopsis: Include documentation from docstrings. + +.. index:: pair: automatic; documentation + single: docstring + +This extension can import the modules you are documenting, and pull in +documentation from docstrings in a semi-automatic way. + +.. note:: + + For Sphinx (actually, the Python interpreter that executes Sphinx) to find + your module, it must be importable. That means that the module or the + package must be in one of the directories on :data:`sys.path` -- adapt your + :data:`sys.path` in the configuration file accordingly. + +.. warning:: + + :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any + modules have side effects on import, these will be executed by ``autodoc`` + when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their main + routine is protected by a ``if __name__ == '__main__'`` condition. + +For this to work, the docstrings must of course be written in correct +reStructuredText. You can then use all of the usual Sphinx markup in the +docstrings, and it will end up correctly in the documentation. Together with +hand-written documentation, this technique eases the pain of having to maintain +two locations for documentation, while at the same time avoiding +auto-generated-looking pure API documentation. + +If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText, +you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension. +:mod:`napoleon <sphinx.ext.napoleon>` is a preprocessor that converts your +docstrings to correct reStructuredText before :mod:`autodoc` processes them. + +.. _Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings +.. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + + +Directives +---------- + +:mod:`autodoc` provides several directives that are versions of the usual +:rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they +import the corresponding module and extract the docstring of the given objects, +inserting them into the page source under a suitable :rst:dir:`py:module`, +:rst:dir:`py:class` etc. directive. + +.. note:: + + Just as :rst:dir:`py:class` respects the current :rst:dir:`py:module`, + :rst:dir:`autoclass` will also do so. Likewise, :rst:dir:`automethod` will + respect the current :rst:dir:`py:class`. + + +.. rst:directive:: automodule + autoclass + autoexception + + Document a module, class or exception. All three directives will by default + only insert the docstring of the object itself:: + + .. autoclass:: Noodle + + will produce source like this:: + + .. class:: Noodle + + Noodle's docstring. + + The "auto" directives can also contain content of their own, it will be + inserted into the resulting non-auto directive source after the docstring + (but before any automatic member documentation). + + Therefore, you can also mix automatic and non-automatic member documentation, + like so:: + + .. autoclass:: Noodle + :members: eat, slurp + + .. method:: boil(time=10) + + Boil the noodle *time* minutes. + + .. rubric:: Options + + .. rst:directive:option:: members + :type: no value or comma separated list + + If set, autodoc will generate document for the members of the target + module, class or exception. + + For example:: + + .. automodule:: noodle + :members: + + will document all module members (recursively), and :: + + .. autoclass:: Noodle + :members: + + will document all class member methods and properties. + + By default, autodoc will not generate document for the members that are + private, not having docstrings, inherited from super class, or special + members. + + For modules, ``__all__`` will be respected when looking for members unless + you give the ``ignore-module-all`` flag option. Without + ``ignore-module-all``, the order of the members will also be the order in + ``__all__``. + + You can also give an explicit list of members; only these will then be + documented:: + + .. autoclass:: Noodle + :members: eat, slurp + + .. rst:directive:option:: undoc-members + :type: no value + + If set, autodoc will also generate document for the members not having + docstrings:: + + .. automodule:: noodle + :members: + :undoc-members: + + .. rst:directive:option:: private-members + :type: no value or comma separated list + + If set, autodoc will also generate document for the private members + (that is, those named like ``_private`` or ``__private``):: + + .. automodule:: noodle + :members: + :private-members: + + It can also take an explicit list of member names to be documented as + arguments:: + + .. automodule:: noodle + :members: + :private-members: _spicy, _garlickly + + .. versionadded:: 1.1 + .. versionchanged:: 3.2 + The option can now take arguments. + + .. rst:directive:option:: special-members + :type: no value or comma separated list + + If set, autodoc will also generate document for the special members + (that is, those named like ``__special__``):: + + .. autoclass:: my.Class + :members: + :special-members: + + It can also take an explicit list of member names to be documented as + arguments:: + + .. autoclass:: my.Class + :members: + :special-members: __init__, __name__ + + .. versionadded:: 1.1 + + .. versionchanged:: 1.2 + The option can now take arguments + + **Options and advanced usage** + + * If you want to make the ``members`` option (or other options described + below) the default, see :confval:`autodoc_default_options`. + + .. tip:: + + You can use a negated form, :samp:`'no-{flag}'`, as an option of + autodoc directive, to disable it temporarily. For example:: + + .. automodule:: foo + :no-undoc-members: + + .. tip:: + + You can use autodoc directive options to temporarily override or + extend default options which takes list as an input. For example:: + + .. autoclass:: Noodle + :members: eat + :private-members: +_spicy, _garlickly + + .. versionchanged:: 3.5 + The default options can be overridden or extended temporarily. + + * autodoc considers a member private if its docstring contains + ``:meta private:`` in its :ref:`info-field-lists`. + For example: + + .. code-block:: python + + def my_function(my_arg, my_other_arg): + """blah blah blah + + :meta private: + """ + + .. versionadded:: 3.0 + + * autodoc considers a member public if its docstring contains + ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with + an underscore. + For example: + + .. code-block:: python + + def _my_function(my_arg, my_other_arg): + """blah blah blah + + :meta public: + """ + + .. versionadded:: 3.1 + + * autodoc considers a variable member does not have any default value if its + docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`. + Example: + + .. code-block:: python + + var1 = None #: :meta hide-value: + + .. versionadded:: 3.5 + + * For classes and exceptions, members inherited from base classes will be + left out when documenting all members, unless you give the + ``inherited-members`` option, in addition to ``members``:: + + .. autoclass:: Noodle + :members: + :inherited-members: + + This can be combined with ``undoc-members`` to document *all* available + members of the class or module. + + It can take an ancestor class not to document inherited members from it. + By default, members of ``object`` class are not documented. To show them + all, give ``None`` to the option. + + For example; If your class ``Foo`` is derived from ``list`` class and + you don't want to document ``list.__len__()``, you should specify a + option ``:inherited-members: list`` to avoid special members of list + class. + + Another example; If your class Foo has ``__str__`` special method and + autodoc directive has both ``inherited-members`` and ``special-members``, + ``__str__`` will be documented as in the past, but other special method + that are not implemented in your class ``Foo``. + + Since v5.0, it can take a comma separated list of ancestor classes. It + allows to suppress inherited members of several classes on the module at + once by specifying the option to :rst:dir:`automodule` directive. + + Note: this will lead to markup errors if the inherited members come from a + module whose docstrings are not reST formatted. + + .. versionadded:: 0.3 + + .. versionchanged:: 3.0 + + It takes an ancestor class name as an argument. + + .. versionchanged:: 5.0 + + It takes a comma separated list of ancestor class names. + + * It's possible to override the signature for explicitly documented callable + objects (functions, methods, classes) with the regular syntax that will + override the signature gained from introspection:: + + .. autoclass:: Noodle(type) + + .. automethod:: eat(persona) + + This is useful if the signature from the method is hidden by a decorator. + + .. versionadded:: 0.4 + + * The :rst:dir:`automodule`, :rst:dir:`autoclass` and + :rst:dir:`autoexception` directives also support a flag option called + ``show-inheritance``. When given, a list of base classes will be inserted + just below the class signature (when used with :rst:dir:`automodule`, this + will be inserted for every class that is documented in the module). + + .. versionadded:: 0.4 + + * All autodoc directives support the ``no-index`` flag option that has the + same effect as for standard :rst:dir:`py:function` etc. directives: no + index entries are generated for the documented object (and all + autodocumented members). + + .. versionadded:: 0.4 + + * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and + ``deprecated`` options that the standard :rst:dir:`py:module` directive + supports. + + .. versionadded:: 0.5 + + * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` + option that can be used to override the global value of + :confval:`autodoc_member_order` for one directive. + + .. versionadded:: 0.6 + + * The directives supporting member documentation also have a + ``exclude-members`` option that can be used to exclude single member names + from documentation, if all members are to be documented. + + .. versionadded:: 0.6 + + * In an :rst:dir:`automodule` directive with the ``members`` option set, only + module members whose ``__module__`` attribute is equal to the module name + as given to ``automodule`` will be documented. This is to prevent + documentation of imported classes or functions. Set the + ``imported-members`` option if you want to prevent this behavior and + document all available members. Note that attributes from imported modules + will not be documented, because attribute documentation is discovered by + parsing the source file of the current module. + + .. versionadded:: 1.2 + + * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent + import errors to halt the building process when some external dependencies + are not importable at build time. + + .. versionadded:: 1.3 + + * As a hint to autodoc extension, you can put a ``::`` separator in between + module name and object name to let autodoc know the correct module name if + it is ambiguous. :: + + .. autoclass:: module.name::Noodle + + * :rst:dir:`autoclass` also recognizes the ``class-doc-from`` option that + can be used to override the global value of :confval:`autoclass_content`. + + .. versionadded:: 4.1 + +.. rst:directive:: autofunction + autodecorator + autodata + automethod + autoattribute + autoproperty + + These work exactly like :rst:dir:`autoclass` etc., + but do not offer the options used for automatic member documentation. + + :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation`` + option. The option controls how the value of variable is shown. If specified + without arguments, only the name of the variable will be printed, and its value + is not shown:: + + .. autodata:: CD_DRIVE + :annotation: + + If the option specified with arguments, it is printed after the name as a value + of the variable:: + + .. autodata:: CD_DRIVE + :annotation: = your CD device name + + By default, without ``annotation`` option, Sphinx tries to obtain the value of + the variable and print it after the name. + + The ``no-value`` option can be used instead of a blank ``annotation`` to show the + type hint but not the value:: + + .. autodata:: CD_DRIVE + :no-value: + + If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no + effect. + + For module data members and class attributes, documentation can either be put + into a comment with special formatting (using a ``#:`` to start the comment + instead of just ``#``), or in a docstring *after* the definition. Comments + need to be either on a line of their own *before* the definition, or + immediately after the assignment *on the same line*. The latter form is + restricted to one line only. + + This means that in the following class definition, all attributes can be + autodocumented:: + + class Foo: + """Docstring for class Foo.""" + + #: Doc comment for class attribute Foo.bar. + #: It can have multiple lines. + bar = 1 + + flox = 1.5 #: Doc comment for Foo.flox. One line only. + + baz = 2 + """Docstring for class attribute Foo.baz.""" + + def __init__(self): + #: Doc comment for instance attribute qux. + self.qux = 3 + + self.spam = 4 + """Docstring for instance attribute spam.""" + + .. versionchanged:: 0.6 + :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract + docstrings. + .. versionchanged:: 1.1 + Comment docs are now allowed on the same line after an assignment. + .. versionchanged:: 1.2 + :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation`` + option. + .. versionchanged:: 2.0 + :rst:dir:`autodecorator` added. + .. versionchanged:: 2.1 + :rst:dir:`autoproperty` added. + .. versionchanged:: 3.4 + :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value`` + option. + + .. note:: + + If you document decorated functions or methods, keep in mind that autodoc + retrieves its docstrings by importing the module and inspecting the + ``__doc__`` attribute of the given function or method. That means that if + a decorator replaces the decorated function with another, it must copy the + original ``__doc__`` to the new function. + + +Configuration +------------- + +There are also config values that you can set: + +.. confval:: autoclass_content + + This value selects what content will be inserted into the main body of an + :rst:dir:`autoclass` directive. The possible values are: + + ``"class"`` + Only the class' docstring is inserted. This is the default. You can + still document ``__init__`` as a separate method using + :rst:dir:`automethod` or the ``members`` option to :rst:dir:`autoclass`. + ``"both"`` + Both the class' and the ``__init__`` method's docstring are concatenated + and inserted. + ``"init"`` + Only the ``__init__`` method's docstring is inserted. + + .. versionadded:: 0.3 + + If the class has no ``__init__`` method or if the ``__init__`` method's + docstring is empty, but the class has a ``__new__`` method's docstring, + it is used instead. + + .. versionadded:: 1.4 + +.. confval:: autodoc_class_signature + + This value selects how the signature will be displayed for the class defined + by :rst:dir:`autoclass` directive. The possible values are: + + ``"mixed"`` + Display the signature with the class name. + ``"separated"`` + Display the signature as a method. + + The default is ``"mixed"``. + + .. versionadded:: 4.1 + +.. confval:: autodoc_member_order + + This value selects if automatically documented members are sorted + alphabetical (value ``'alphabetical'``), by member type (value + ``'groupwise'``) or by source order (value ``'bysource'``). The default is + alphabetical. + + Note that for source order, the module must be a Python module with the + source code available. + + .. versionadded:: 0.6 + .. versionchanged:: 1.0 + Support for ``'bysource'``. + +.. confval:: autodoc_default_flags + + This value is a list of autodoc directive flags that should be automatically + applied to all autodoc directives. The supported flags are ``'members'``, + ``'undoc-members'``, ``'private-members'``, ``'special-members'``, + ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'`` + and ``'exclude-members'``. + + .. versionadded:: 1.0 + + .. deprecated:: 1.8 + + Integrated into :confval:`autodoc_default_options`. + +.. confval:: autodoc_default_options + + The default options for autodoc directives. They are applied to all autodoc + directives automatically. It must be a dictionary which maps option names + to the values. For example:: + + autodoc_default_options = { + 'members': 'var1, var2', + 'member-order': 'bysource', + 'special-members': '__init__', + 'undoc-members': True, + 'exclude-members': '__weakref__' + } + + Setting ``None`` or ``True`` to the value is equivalent to giving only the + option name to the directives. + + The supported options are ``'members'``, ``'member-order'``, + ``'undoc-members'``, ``'private-members'``, ``'special-members'``, + ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``, + ``'imported-members'``, ``'exclude-members'``, ``'class-doc-from'`` and + ``'no-value'``. + + .. versionadded:: 1.8 + + .. versionchanged:: 2.0 + Accepts ``True`` as a value. + + .. versionchanged:: 2.1 + Added ``'imported-members'``. + + .. versionchanged:: 4.1 + Added ``'class-doc-from'``. + + .. versionchanged:: 4.5 + Added ``'no-value'``. + +.. confval:: autodoc_docstring_signature + + Functions imported from C modules cannot be introspected, and therefore the + signature for such functions cannot be automatically determined. However, it + is an often-used convention to put the signature into the first line of the + function's docstring. + + If this boolean value is set to ``True`` (which is the default), autodoc will + look at the first line of the docstring for functions and methods, and if it + looks like a signature, use the line as the signature and remove it from the + docstring content. + + autodoc will continue to look for multiple signature lines, + stopping at the first line that does not look like a signature. + This is useful for declaring overloaded function signatures. + + .. versionadded:: 1.1 + .. versionchanged:: 3.1 + + Support overloaded signatures + + .. versionchanged:: 4.0 + + Overloaded signatures do not need to be separated by a backslash + +.. confval:: autodoc_mock_imports + + This value contains a list of modules to be mocked up. This is useful when + some external dependencies are not met at build time and break the building + process. You may only specify the root package of the dependencies + themselves and omit the sub-modules: + + .. code-block:: python + + autodoc_mock_imports = ["django"] + + Will mock all imports under the ``django`` package. + + .. versionadded:: 1.3 + + .. versionchanged:: 1.6 + This config value only requires to declare the top-level modules that + should be mocked. + +.. confval:: autodoc_typehints + + This value controls how to represent typehints. The setting takes the + following values: + + * ``'signature'`` -- Show typehints in the signature (default) + * ``'description'`` -- Show typehints as content of the function or method + The typehints of overloaded functions or methods will still be represented + in the signature. + * ``'none'`` -- Do not show typehints + * ``'both'`` -- Show typehints in the signature and as content of + the function or method + + Overloaded functions or methods will not have typehints included in the + description because it is impossible to accurately represent all possible + overloads as a list of parameters. + + .. versionadded:: 2.1 + .. versionadded:: 3.0 + + New option ``'description'`` is added. + + .. versionadded:: 4.1 + + New option ``'both'`` is added. + +.. confval:: autodoc_typehints_description_target + + This value controls whether the types of undocumented parameters and return + values are documented when ``autodoc_typehints`` is set to ``description``. + + The default value is ``"all"``, meaning that types are documented for all + parameters and return values, whether they are documented or not. + + When set to ``"documented"``, types will only be documented for a parameter + or a return value that is already documented by the docstring. + + With ``"documented_params"``, parameter types will only be annotated if the + parameter is documented in the docstring. The return type is always + annotated (except if it is ``None``). + + .. versionadded:: 4.0 + + .. versionadded:: 5.0 + + New option ``'documented_params'`` is added. + +.. confval:: autodoc_type_aliases + + A dictionary for users defined `type aliases`__ that maps a type name to the + full-qualified object name. It is used to keep type aliases not evaluated in + the document. Defaults to empty (``{}``). + + The type aliases are only available if your program enables :pep:`Postponed + Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import + annotations``. + + For example, there is code using a type alias:: + + from __future__ import annotations + + AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + def f() -> AliasType: + ... + + If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up + from this code as following:: + + .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + ... + + If you set ``autodoc_type_aliases`` as + ``{'AliasType': 'your.module.AliasType'}``, it generates the following document + internally:: + + .. py:function:: f() -> your.module.AliasType: + + ... + + .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases + .. versionadded:: 3.3 + +.. confval:: autodoc_typehints_format + + This value controls the format of typehints. The setting takes the + following values: + + * ``'fully-qualified'`` -- Show the module name and its name of typehints + * ``'short'`` -- Suppress the leading module names of the typehints + (ex. ``io.StringIO`` -> ``StringIO``) (default) + + .. versionadded:: 4.4 + + .. versionchanged:: 5.0 + + The default setting was changed to ``'short'`` + +.. confval:: autodoc_preserve_defaults + + If True, the default argument values of functions will be not evaluated on + generating document. It preserves them as is in the source code. + + .. versionadded:: 4.0 + + Added as an experimental feature. This will be integrated into autodoc core + in the future. + +.. confval:: autodoc_warningiserror + + This value controls the behavior of :option:`sphinx-build -W` during + importing modules. + If ``False`` is given, autodoc forcedly suppresses the error if the imported + module emits warnings. By default, ``True``. + +.. confval:: autodoc_inherit_docstrings + + This value controls the docstrings inheritance. + If set to True the docstring for classes or methods, if not explicitly set, + is inherited from parents. + + The default is ``True``. + + .. versionadded:: 1.7 + +.. confval:: suppress_warnings + :no-index: + + :mod:`autodoc` supports to suppress warning messages via + :confval:`suppress_warnings`. It allows following warnings types in + addition: + + * autodoc + * autodoc.import_object + + +Docstring preprocessing +----------------------- + +autodoc provides the following additional events: + +.. event:: autodoc-process-docstring (app, what, name, obj, options, lines) + + .. versionadded:: 0.4 + + Emitted when autodoc has read and processed a docstring. *lines* is a list + of strings -- the lines of the processed docstring -- that the event handler + can modify **in place** to change what Sphinx puts into the output. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive + :param lines: the lines of the docstring, see above + +.. event:: autodoc-before-process-signature (app, obj, bound_method) + + .. versionadded:: 2.4 + + Emitted before autodoc formats a signature for an object. The event handler + can modify an object to change its signature. + + :param app: the Sphinx application object + :param obj: the object itself + :param bound_method: a boolean indicates an object is bound method or not + +.. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation) + + .. versionadded:: 0.5 + + Emitted when autodoc has formatted a signature for an object. The event + handler can return a new tuple ``(signature, return_annotation)`` to change + what Sphinx puts into the output. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive + :param signature: function signature, as a string of the form + ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't + succeed and signature wasn't specified in the directive. + :param return_annotation: function return annotation as a string of the form + ``" -> annotation"``, or ``None`` if there is no return annotation + +The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly +needed docstring processing in event :event:`autodoc-process-docstring`: + +.. autofunction:: cut_lines +.. autofunction:: between + +.. event:: autodoc-process-bases (app, name, obj, options, bases) + + Emitted when autodoc has read and processed a class to determine the + base-classes. *bases* is a list of classes that the event handler can + modify **in place** to change what Sphinx puts into the output. It's + emitted only if ``show-inheritance`` option given. + + :param app: the Sphinx application object + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the class directive + :param bases: the list of base classes signature. see above. + + .. versionadded:: 4.1 + .. versionchanged:: 4.3 + + ``bases`` can contain a string as a base class name. It will be processed + as reST mark-up'ed text. + + +Skipping members +---------------- + +autodoc allows the user to define a custom method for determining whether a +member should be included in the documentation by using the following event: + +.. event:: autodoc-skip-member (app, what, name, obj, skip, options) + + .. versionadded:: 0.5 + + Emitted when autodoc has to decide whether a member should be included in the + documentation. The member is excluded if a handler returns ``True``. It is + included if the handler returns ``False``. + + If more than one enabled extension handles the ``autodoc-skip-member`` + event, autodoc will use the first non-``None`` value returned by a handler. + Handlers should return ``None`` to fall back to the skipping behavior of + autodoc and other enabled extensions. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param skip: a boolean indicating if autodoc will skip this member if the + user handler does not override the decision + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive |