5

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"?

Prof. Falken
  • 24,226
  • 19
  • 100
  • 173

3 Answers3

2

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.

Bonlenfum
  • 19,101
  • 2
  • 53
  • 56
  • You are right, I have been looking in the wrong place I think. Weird thing is, platform shows up in the index if I add the platform word, synopsis *still* does not. :) – Prof. Falken Jan 17 '13 at 07:41
  • The 0-indented synopsis does show where automodule is, but there I don't need a synopsis, it just looks cluttered there. :-/ In index... nothing. Checking now with various indentation levels. – Prof. Falken Jan 17 '13 at 08:35
  • The weird thing is that is clearly picks up the platform in the index, but not the synopsis. – Prof. Falken Jan 17 '13 at 08:41
  • Trying to follow the Google recommendation did not work either, it just got added to the module documentation text. – Prof. Falken Jan 17 '13 at 08:47
  • I guess I will have to misuse the platform directive for synopsis. :-D – Prof. Falken Jan 17 '13 at 08:58
  • @Prof.Falken I gave a full working example where you do not have to misrepresent a synopsis – ecoe Jan 11 '14 at 18:54
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.

brianmearns
  • 9,581
  • 10
  • 52
  • 79
  • I use ... wha? What do propose I do, specifically? Or do you mean it's not possible. Weird then that it picked up the platform tag. Maybe *that* is a bug. – Prof. Falken Jan 17 '13 at 16:56
2

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

ecoe
  • 4,994
  • 7
  • 54
  • 72
  • I usually do everything in html, I might try it in pdf within a week or so. I will update this comment when I do. – ecoe Jan 12 '14 at 17:32