I think we need to support field list option 3 (``reStructuredText.txt`` revision 1.1.1.1 line 478) to support PEP-0257 style usage docstrings in Python scripts without preventing script authors from specifying bibliographic field lists. Background: The reStructuredText spec supports field lists of RFC-822 style headers:: Special case: use unadorned RFC822_ for the very first or very last text block of a docstring:: """ Author: Me Version: 1 The rest of the docstring... """ Note that it says *docstring*, not *document*. :) Later, the spec says:: One special context is defined for field lists. A field list as the very first non-comment block, or the second non-comment block immediately after a title, is interpreted as document bibliographic data. No special syntax is required, just unadorned RFC822_. The first ... Making the least effort to eliminate ambiguity, I come up with: * When using reStructuredText in docstrings, you can have as many field lists as you like, in any docstring, so long as they're either the first or last block in the docstring. - In a document, you can have only two: one at the beginning, and one at the end. * A field list as the first non-comment block in a document becomes ``document bibliographic data``. - In docstrings, this becomes tricky. To me, it ends up saying that a field list at the top of the *first docstring* (the second if the first is a title) becomes bibliographic data for the file. PEP-0257 says:: The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a docstring should document the script's function ... To cut a long story short, when these two lock horns it looks like we can't have reStructuredText bibliographic field lists in scripts because otherwise the script couldn't print its usage with a simple ``print __doc__``. If by this point you've already figured out how to resolve the issue by straightening out wording in the spec, not changing any code, please let me know. :) The simplest fix I can see is to accept the previously-rejected "option 3" of a ``fields`` directive:: .. fields:: If specified, it would signal to the parser that the next text block was a field list, not a paragraph. Furthermore; if it was the first field list in the document (ie there wasn't one at the top), the field list would be treated as bibliographic data. The ``fields`` directive would not be required for field lists at the beginning or end of a document or docstring. We might generate a warning. Regards, Garth. PS: The usage for many scripts looks like this:: """\ Usage: cvs [cvs-options] command [command-options-and-arguments] where ... """ Perhaps we should suppress recognition of bibliographic field lists without generating warnings if the first field name seems to be ``Usage``.