5

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Nick T
  • 25,754
  • 12
  • 83
  • 121

3 Answers3

7

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.

simno
  • 418
  • 9
  • 14
4

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.

Kevin Horn
  • 4,167
  • 28
  • 30
  • `currentmodule` doesn't accept the `:synopsis:` option so I need to move that to the rST file, then having any `module` directive in the source is superfluous. I'm wondering if what I want isn't possible (at present). `:/` – Nick T May 15 '13 at 18:38
0

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.

Grimthorr
  • 6,856
  • 5
  • 41
  • 53
Mike
  • 1
  • 1