CODEWITHSUNDEEP
pythonpython-sphinxautodoc
Nick T
Nick T

Reputation: 26717

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

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.

Upvotes: 5

Views: 3717

Answers (3)

Mike
Mike

Reputation: 1

The :noindex: for automodule:: as written by simno helps but prevents the creation of perma-links and cross-links (e.g. :func:) won't work. When adding :noindex: to module:: everything works as expected and you don't have to use currentmodule.

Upvotes: 0

simno
simno

Reputation: 448

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.

Upvotes: 7

Kevin Horn
Kevin Horn

Reputation: 4295

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.

Upvotes: 4

Related Questions