How to specialize documenters in sphinx autodoc
<p>I am documenting a project with Sphinx I want to create a specialized version of the <code>autoclass::</code> directive that allows me to modify the documentation string for certain classes.</p>

<p>Here is one thing I have tried: searching the sphinx source, I found that the <code>autoclass</code> directive is created via the <a href="https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc.py#L1216" rel="nofollow"><code>ClassDocumenter</code> object</a>. Following this, my idea was to register a subclass of <code>ClassDocumenter</code> for the classes of interest, and then override <code>get_doc</code> to modify the docstring.</p>

<p>Here's my attempt at such an extension:</p>

<pre><code>from six import class_types
from sphinx.ext.autodoc import ClassDocumenter
from testmodule import Foo  # the class that needs modified documentation


class MyClassDocumenter(ClassDocumenter):
    objtype = 'myclass'
    priority = 20  # higher priority than ClassDocumenter

    @classmethod
    def can_document_member(cls, member, membername, isattr, parent):
        return isinstance(member, class_types) and issubclass(member, Foo)

    def get_doc(self, encoding=None, ignore=1):
        doc = super(MyClassDocumenter, self).get_doc(encoding, ignore)
        # do something to modify the output documentation
        doc[0].insert(0, "ADD SOMETHING TO THE DOC")
        return doc

def setup(app):
    app.add_autodocumenter(MyClassDocumenter)
</code></pre>

<p>The problem is, when I run this I get an error: <code>ERROR: Unknown directive type "py:myclass".</code> It seems that registering a documenter is not enough to register the associated directive, but I've not been able to find any clues in the sphinx source to tell me how such a registration is supposed to happen. It's not as simple as using the standard <code>add_directive()</code> methods, because I have no explicit directive to register.</p>

<p>How can I correctly accomplish such a specialization of an auto-documenter in sphinx?</p>

<p>(note: the full set of files to reproduce the error is available <a href="https://gist.github.com/jakevdp/34a57475bce1bf210667630aa622f407" rel="nofollow">in this gist</a>)</p>

<p><code>Documenter</code> classes require an existing directive to apply, when appropriate. This can either be a "built in" directive, or it can be a custom directive you create and register. Either way, the directive to use is specified by the <code>directivetype</code> class attribute. You can specify this value explicitly:</p>

<pre><code>class MyClassDocumenter(ClassDocumenter):
    directivetype = 'foo' # corresponds to :foo: in the doc source
    objtype = 'bar'
    priority = 20  
</code></pre>

<p>Or, it looks like you can omit <code>directivetype</code> and it will use the same value as <code>objtype</code> by default. (This is an educated guess)</p>

<p>So then the question is: have you registered a new directive for <code>:myclass:</code>? If not I think that is the problem. Alternatively, if there is some other directive that you want to be used (whether built-in, or custom) the answer is probably to specify it explicitly by including a value for <code>directivetype</code> in your <code>Documenter</code> class definition. </p>

python python-sphinx