Adding the "Description-Content-Type" metadata field
Hi folks,
Marc Abramowitz has prepared a PR for the Core Metadata section of the
specifications page [1] that adds a new "Description-Content-Type"
field: https://github.com/pypa/python-packaging-user-guide/pull/258
The draft text has now reached the point where I'm prepared to accept
it, so this thread offers folks one last chance to provide feedback
before we make it official.
Full text of the new subsection
=========================================
Description-Content-Type
~~~~~~~~~~~~~~~~~~~~~~~~
A string containing the format of the distribution's description, so that
tools can intelligently render the description.
Historically, PyPI supported descriptions in plain text and `reStructuredText
(reST) http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html`_,
and could render reST into HTML. However, it is common for distribution
authors to write the description in `Markdown
https://daringfireball.net/projects/markdown/`_ (`RFC 7763
https://tools.ietf.org/html/rfc7763`_) as many code hosting sites render
Markdown READMEs, and authors would reuse the file for the description. PyPI
didn't recognize the format and so could not render the description correctly.
This resulted in many packages on PyPI with poorly-rendered descriptions when
Markdown is left as plain text, or worse, was attempted to be rendered as reST.
This field allows the distribution author to specify the format of their
description, opening up the possibility for PyPI and other tools to be able to
render Markdown and other formats.
The format of this field is the same as the ``Content-Type`` header in HTTP
(e.g.:
`RFC 1341 https://www.w3.org/Protocols/rfc1341/4_Content-Type.html`_).
Briefly, this means that it has a ``type/subtype`` part and then it can
optionally have a number of parameters:
Format::
Description-Content-Type: <type>/<subtype>; charset=<charset>[;
participants (1)
-
Nick Coghlan