Question

我使用以下方法将包上传到PyPi：

python setup.py register -r pypi
python setup.py sdist upload -r pypi

我正在尝试修改decsription，我写道（请不要编辑以下代码片段的格式，我是为了演示我的问题而制作的）：

**nose-docstring-plugin**

This plugin enables you to modify docstring of tests based on their attributes, for example:
```python
@attr(section='MySection', type='functional+', module='MyModule', id=1)
def test_function(self):
    """
    This is the original docstring
    """
    pass
```

但是，文本显示为原样，没有降价格式。我做错了什么？

Answer 1

截至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完全相同的;它基本上是相同的渲染器。

您可以使用twine check command（long_description 1.12.0或更高版本）验证您的资料包twine。

旧＆lt; 2018-03-16答案如下。

注意：这是旧的，现在过时的答案，截至2018-03-16支持Markdown，只要您使用正确的工具，请参阅上面的。

PyPI 不支持Markdown，因此您的README不会呈现为HTML。

如果你想要一个渲染的自述文件，请坚持使用reStructuredText; Sphinx introduction to reStructuredText是一个很好的起点。

您可能希望安装docutils package，以便在本地测试您的文档;您希望在README上运行包含的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的支持。

Answer 2

正如@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,
)

要在OS X上安装Pandoc，我使用了Homebrew：

brew install pandoc

要安装PyPandoc，我使用了pip：

pip install pypandoc

Answer 3

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。

Answer 4

我遇到了导致解析问题的\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（）函数。

Answer 5

有一个很好的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)

我还创建了一个可以在py.test中使用的lib

https://github.com/pablodav/burp_server_reports/blob/master/burp_reports/lib/check_readme.py

Answer 6

您也可以在setup.cfg文件中设置降价：

[metadata]
...
description-file = README.md
long-description-content-type = text/markdown

以我的项目为例：在github和pypi上。

PyPi描述降价不起作用

6 个答案: