Search code examples
pythonpython-sphinxrestructuredtextbibliography

reStructuredText Bibliographic fields proper usage


What is the proper way to use the reStructuredText Bibliographic fields for a python file?


Solution

  • The most prominent example of how to use such fields is in the Python PEPs, e.g. PEP-0414:

    PEP: 414
    Title: Explicit Unicode Literal for Python 3.3
    Version: $Revision$
    Last-Modified: $Date$
    Author: Armin Ronacher <[email protected]>,
            Nick Coghlan <[email protected]>
    Status: Final
    Type: Standards Track
    Content-Type: text/x-rst
    Created: 15-Feb-2012
    Post-History: 28-Feb-2012, 04-Mar-2012
    Resolution: http://mail.python.org/pipermail/python-dev/2012-February/116995.html
    

    While this is a longish list of fields, it shows how they are used.

    As explained in the reST documentation,

    This bibliographic data corresponds to the front matter of a book, such as the title page and copyright page.

    so there should be only one set of such fields per document, namely at the beginning. Don't forget that reST was developed as a lightweight markup for Python documentation.