:synopsis: not working in Sphinx automodule

Question

I am using Sphinx, really like it, but it won't pick up the module synopsis. No error or anything, just plain ... nothing. This is the module I am trying to autodocument:

# vim: set fileencoding=utf-8 :
"""
.. module:: CONF
   :synopsis: Configuration module, tells where data files are.

.. moduleauthor:: Mr Anderson <[email protected]>
"""

This is the Sphinx directive in the ReST index file:

.. automodule:: CONF
   :synopsis:

I get all sorts of other wonderful things from Sphinx, so it's not generally broken for me. The only suspicious thing I get is: SEVERE: Duplicate ID: "module-CONF". Some googling led me to believe though that this error is quite "normal"?

Answer 1

Not sure whether this really answers your question, but perhaps you are looking in the 'wrong' place for the synopsis to get picked up. ('wrong' because it seems pretty reasonable to expect it to come out where your automodule directive is). From the documentation on module markup (emphasis mine):

synopsis option should consist of one sentence describing the module’s purpose – it is currently only used in the Global Module Index.

So for the module comment string:

"""

.. module:: CONF
  :synopsis: Configuration module, tells where data files are.
    continuation possible here... (though goes against the point of synopses...)
  :platform: Windows

"""

the synopsis comes out in the module index -- something like

c

CONF (Windows) Configuration module, ....

Alternatively, for the module comment string (note indentation):

"""

:synopsis: Configuration module, tells where data files are to.

"""

will get rendered where you put in the automodule:: directive, but not in the module index. For me the styling is as parameters are rendered in member functions.

As a somewhat nasty workaround, you could combine these two :synopsis: declarations, though clearly that's not very maintainable.

Answer 2

I think you're using the :synopsis: option incorrectly on the automodule directive. You use this option the same on automodule as you do on module. In other words, you have to specify the synopsis inline with the :synopsis: option on either of the directives.

Generally, you use either the module directive or the automodule directive, not both. This is also why you're getting the warning about duplicates. It's unfortunate because, as far as I've been able to find, there's no way to include the synopsis in the docstring if you're using automodule

So if you want to use automodule and synopsis without getting the warning, I think you have to do this:

.. automodule:: CONF
   :synopsis: Configuration module, tells where data files are.

And then get rid of the `.. module:: directive in the src file itself.

I think the way you have it will work, but you'll get that warning. Also, you should delete the :synopsis: option from the automodule: without an actual synopsis string following it, it doesn't do you any good and could lead to having an "empty" synopsis.