How do I avoid "SEVERE: Duplicate ID" warnings for my autodoc'd modules in Sphinx?

Question

I'm using rST/Sphinx to document my Python, however when building it's throwing warnings such as

...Code/doc/code.rst:3: SEVERE: Duplicate ID: "module-toast".

My Python source files are documented like so:

#!/usr/bin/env python
'''
.. module:: toast
    :synopsis: Processes the blobs produced by :mod:`bread`.
'''
# my inline-rST documented code...

And the rST files use the autodoc provided automodule directive to pull all the docstrings out and document all the members.

Toast
--------------------------------

.. automodule:: toast
    :members:

The above combo seems to work just fine, but the error seems to imply there is a proper way to do this. If I remove the module directive from the top of my source file the error goes away, but then I can't add a synopsis option in the source that's picked up by Sphinx.

Answer 1

One way around is to use :noindex: flag.

.. automodule:: toast
    :members:
    :noindex:

Then in your source code you can use:

#!/usr/bin/env python
'''
.. module:: toast
    :synopsis: Processes the blobs produced by :mod:`bread`.
'''

There'll be no SEVERE warning and message in synopsis will appear in module index.

On the other side :noindex: will hide module from index if it doesn't have .. module:: in their source file.

Answer 2

I'm not sure, but I believe that the automodule directive will create a module directive on it's own. Then, since you already have one specified, there are two, and thus you get a duplicate ID message.

You might try using the currentmodule directive in your module markup instead of module. It seems like that should work, though I admit I haven't actually tried it.