PyPi描述降价不起作用

Question

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

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

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

**my plugin**

This plugin enables you to ... For example:
```python
@attr(section='MySection', id=1)
def test_function(self):
    """
    Bla bla bla
    """
    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 - Python软件包的元数据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库(readme_renderer.markdown.render(long_description)用于生成HTML输出)用作降价渲染器.这意味着您的降价文档将呈现与 GitHub 完全相同的内容 ; 它基本上是相同的渲染器.

您可以long_description使用twine check命令(twine1.12.0或更高版本)验证您的包.

旧的<2018-03-16答案如下.

注意:这是旧的,现在过时的答案,截至2018-03-16支持Markdown,前提是您使用正确的工具,见上文.

PyPI将它不支持降价,所以你的自述不会被渲染成HTML.

如果你想要一个渲染的自述文件,请坚持使用reStructuredText; 在狮身人面像的介绍新结构化是一个很好的起点.

您可能希望安装该docutils软件包,以便在本地测试您的文档; 您希望rst2html.py在README上运行包含的脚本,以查看生成的错误(如果有).您的特定样本有太多错误:

$ 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.

有一个上拉的请求功能要求添加支持降价,如果你有兴趣.

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坚持,只是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

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

[metadata]
...
long_description = file: README.md
long_description_content_type = text/markdown

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