我使用以下方法将包上传到PyPi：
python setup.py register -r pypi
python setup.py sdist upload -r pypi
我正在尝试修改描述，我写了（请不要编辑以下代码片段的格式，我是故意为了演示我的问题）：
**my plugin**
This plugin enables you to ... For example:
```python
@attr(section='MySection', id=1)
def test_function(self):
"""
Bla bla bla
"""
pass
```
但是，文本显示为原样，没有降价格式。我究竟做错了什么？
截至2018年3月16日，PyPI.org aka Warehouse（最后）在长描述中支持Markdown。 Warehouse于2018年4月取代了旧的传统PyPI实施。
你需要：
setuptools升级到38.6.0或更高版本twine升级到1.11.0或更高版本wheel升级到0.31.0或更高版本long_description_content_type调用中添加一个名为setup()的新字段，并将其设置为'text/markdown'：
setup(
long_description="""# Markdown supported!\n\n* Cheer\n* Celebrate\n""",
long_description_content_type='text/markdown',
# ....
)
见PEP 566 - Metadata for Python Software Packages 2.1。twine将您的发行版上传到PyPI：
$ python setup.py sdist bdist_wheel # adjust as needed
$ twine upload dist/*
旧的传统PyPI基础架构不会呈现Markdown，只有新的Warehouse基础架构才能实现。遗留基础设施现已消失（截至2018-04-30）。
目前，PyPI使用cmarkgfm作为降价渲染器，通过readme_renderer library（使用readme_renderer.markdown.render(long_description)生成HTML输出）。这意味着您的降价文档将呈现与GitHub完全相同的内容;它基本上是相同的渲染器。
您可以使用long_description（twine check command 1.12.0或更高版本）验证您的包twine。
旧的<2018-03-16答案如下。
注意：这是旧的，现在过时的答案，截至2018-03-16支持Markdown，前提是您使用正确的工具，见上文。
PyPI不支持Markdown，因此您的README不会呈现为HTML。
如果你想要一个渲染的自述文件，请坚持使用reStructuredText; Sphinx introduction to reStructuredText是一个很好的起点。
您可能想安装docutils package，以便在本地测试您的文档;你想在自述文件中运行包含的rst2html.py脚本，看看产生了什么错误，如果有的话。您的特定样本有太多错误：
$ bin/rst2html.py test.rst > /tmp/test.html
test.rst:7: (ERROR/3) Unexpected indentation.
test.rst:3: (WARNING/2) Inline literal start-string without end-string.
test.rst:3: (WARNING/2) Inline interpreted text or phrase reference start-string without end-string.
test.rst:11: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
test.rst:11: (WARNING/2) Inline literal start-string without end-string.
test.rst:11: (WARNING/2) Inline interpreted text or phrase reference start-string without end-string.
您的代码块使用的是Github的Markdown扩展，这对于reStructuredText完全错误。您可以使用reST代码块（可能，如果Docutil的PyPI版本足够新）：
.. code-block:: python
@attr(section='MySection', type='functional+', module='MyModule', id=1)
def test_function(self):
"""
This is the original docstring
"""
pass
要在本地测试，您还需要安装Pygments。
如果您有兴趣，有一个feature request with pull request可以添加对Markdown的支持。
正如@Martijn Pieters所说，PyPi不支持Markdown。我不确定在哪里学到了以下技巧，但你可以使用Pandoc和PyPandoc将你的Markdown文件转换为RestructuredText，然后再上传到PyPi。要完成此操作，请将以下内容添加到setup.py文件中：
try:
import pypandoc
long_description = pypandoc.convert('README.md', 'rst')
except(IOError, ImportError):
long_description = open('README.md').read()
setup(
name='blah',
version=find_version('blah.py'),
description='Short description',
long_description=long_description,
)
brew install pandoc
pip install pypandoc
PyPI支持rst，而不是其他答案中提到的降价。但你不需要pypandoc perse，只需pandoc就可以了。您可以先在本地生成第一个文件，然后运行setup.py来上传包。
upload.sh：
#!/bin/bash
pandoc --from=markdown --to=rst --output=README README.md
python setup.py sdist upload
将自动识别名为README的生成文件。一定要把它添加到你的.gitignore！ setup.py不需要做任何特别的事情。
setup.py：
from distutils.core import setup
setup(
name='mypackage',
packages=['mypackage'], # this must be the same as the name above
version='0.2.8',
description='short',
author='Chiel ten Brinke',
author_email='<email>',
url='<github url>', # use the URL to the github repo
keywords=[], # arbitrary keywords
classifiers=[],
)
然后运行bash upload.sh将内容上传到PyPI。
我遇到过\r字符问题导致解析问题，其中只有README的第一行出现在pypi中。下面的代码修复了这个问题，它来自pypandoc模块库：
try:
long_description = pypandoc.convert('README.md', 'rst')
long_description = long_description.replace("\r","") # Do not forget this line
except OSError:
print("Pandoc not found. Long_description conversion failure.")
import io
# pandoc is not installed, fallback to using raw contents
with io.open('README.md', encoding="utf-8") as f:
long_description = f.read()
这样，long_description包含自述文件的清理版本，您可以将其传递给setup.py脚本中的setup（）函数。
有一个很好的pip包对我有用
https://pypi.python.org/pypi/restructuredtext_lint/
我现在在我的设置上使用它：
https://github.com/pablodav/burp_server_reports/blob/master/setup.py
def check_readme(file='README.rst'):
"""
Checks readme rst file, to ensure it will upload to pypi and be formatted correctly.
:param file:
:return:
"""
errors = rst_lint.lint_file(file)
if errors:
msg = 'There are errors in {}, errors \n {}'.format(file, errors[0].message)
raise SystemExit(msg)
else:
msg = 'No errors in {}'.format(file)
print(msg)
我还创建了一个lib，以便以后可以在py.test中使用
https://github.com/pablodav/burp_server_reports/blob/master/burp_reports/lib/check_readme.py