How can I apply :special-members: to just one class inside an automodule directive?

Question

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 automodule:: directive, I have a specific class to which I want to apply the :special-members: flag. Flagging the automodule:: with :special-members: shows the specials for everything in the module, and that's no good.

How can I do this?

Adding an autoclass:: directive flagged with :special-members: still leaves the "non-specialized" documentation there as part of the automodule:: content, resulting in duplicated content.

I suppose I could explicitly type out all of the classes in the module except my specials-targeted one in a :members: instruction on the automodule::, but then I'd have to remember to update that list every time I added or removed a class to the module.

Answer 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."""


class ClassA:
    """ClassA docstring."""

    def __special_func_one__(self, two):
        """Special method docstring."""
        self.two = two

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


class ClassB:
    """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.