How Can I Apply :special-members: To Just One Class Inside An Automodule Directive?

I am putting together Sphinx-driven (v1.3.1) documentation for a Python 2.7 project using autodoc and napoleon. Inside one module, which I'd like to document with a single automod

Solution 1:

The solution for this is excluding the members that you want different options applied to in automodule. Afterwards include them with their own directive, setting the particular options you want on that directive.

The following example excludes ClassB from the automodule directive. Afterwards ClassB is included in the context of the automodule with its own autoclass directive. Under the :special-members: option set only the members you want shown.

Corresponding .rst file:

selective module
================

.. automodule:: selective
    :members:
    :exclude-members: ClassB

    .. autoclass:: ClassB
        :special-members: __init__, __special_func_two__

Corresponding .py file:

"""This modules docstring."""classClassA:
    """ClassA docstring."""def__special_func_one__(self, two):
        """Special method docstring."""
        self.two = two

    def__init__(self, one):
        """Special method docstring."""
        self.one = one


classClassB:
    """ClassB docstring."""def__special_func_two__(self, two):
        """Special method docstring."""
        self.two = two

    def__special_func_three__(self, three):
        """Special method docstring."""
        self.three = three

    def__init__(self, one):
        """Special method docstring."""
        self.one = one

This minimizes the number of exceptions you have to type because default rules still apply normally to the remaining members of the module, except when you indicate otherwise. In most IDEs this solution will also refactor changes made to the Python source code.

For the exact solution shown special-members and private-members were not included in autodoc_default_options inside conf.py. The relevant sphinx.ext.napoleon setting was set to napoleon_include_special_with_doc = False. However, the individual directive settings would still take precedence over the former general configurations.