问题
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 <mr@matrix.com>
"""
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"?
回答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.
回答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.
回答3:
Following Bonlenfum's solution, here's an (even more) succinct example that prints the module directives in both the module index and doc strings:
"""
.. module:: CONF
:synopsis: written in module index..................................newlines are
automatically handled (still, mind the spacing)
:platform: Windows
.. moduleauthor:: Mr Anderson <mr@matrix.com>
:synopsis: this is written in the docstrings..........................newlines are handled
automatically handled (mind spacing) or I can force newlines with \n
a newline character.
"""
I added the "..." to add space such that the line is long enough for sphinx to automatically continue on a newline. The module author is only shown in the doc strings (not index).
this worked nicely with Sphinx 1.2 and read the docs theme
来源：https://stackoverflow.com/questions/14361140/synopsis-not-working-in-sphinx-automodule