How do I document members in specific sections usi

问题:

I'm struggling to figure out how to place the documentation for specific members of my Python class in specific sections of my Sphinx documentation, ideally while auto-documenting the rest in another section.

I have a Python class

class MyClass(object):

    def funky(self, arg):
        """Some docs."""
        ...

defined in my/module.py which works as expected and I can document without issues using

***************************
MyModule - :mod:`my.module`
***************************

.. automodule:: my.module

.. autoclass:: MyClass
   :members:
   :undoc-members:
   :show-inheritance:

But when I try to get more control over the organization of my documentation I can't get things working. Specifically, I'd like to have some members documented in explicit sections (just one is shown here, but there would be several), with the rest auto-documented as a group.

But when I try this with, for example

***************************
MyModule - :mod:`my.module`
***************************

To document
===========

Things that are not yet documented.

.. automodule:: my.module

.. autoclass:: MyClass
   :members:
   :undoc-members:
   :show-inheritance:
   :exclude-members: funky

Funky things
------------

Some funky things.

.. automethod:: funky

I get

WARNING: don't know which module to import for autodocumenting u'funky' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

but no variations of

.. currentmodule:: my.module
.. class:: MyClass

.. automethod:: funky

or

.. currentmodule:: my.module

   .. automethod:: funky

etc. get me anywhere.

How do I auto-document some members of my class in specific places in my Sphinx documentation?

回答1:

This works:

.. currentmodule:: my.module

.. automethod:: MyClass.funky

You could skip .. currentmodule:: and do it like this:

.. automethod:: my.module.MyClass.funky

A third option:

.. currentmodule:: my.module

.. autoclass:: MyClass   

   .. automethod:: funky