如何使 PyPi 描述 Markdown 工作? [英] How to make PyPi description Markdown work?

问题描述

我上传了一个包到 PyPi 使用:

I uploaded a package to PyPi using:

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

我正在尝试修改描述，我写了(请不要编辑以下代码的格式，我是为了证明我的问题而特意制作的):

I'm trying to modify the description, I wrote (please don't edit the formatting of the following piece of code, I made it on purpose to demonstrate my problem):

**my plugin**

This plugin enables you to ... For example:
```python
@attr(section='MySection', id=1)
def test_function(self):
    """
    Bla bla bla
    """
    pass
```

但是，文本按原样显示，没有 Markdown 格式.我做错了什么?

However, the text appears as it is, without the markdown formatting. What am I doing wrong?

推荐答案

截至 2018 年 3 月 16 日，PyPI.org aka Warehouse(终于)在长描述中支持 Markdown.Warehouse 在 2018 年 4 月替换了旧的 PyPI 实现.

As of March 16, 2018, PyPI.org aka Warehouse (finally) supports Markdown in long descriptions. Warehouse replaced the old legacy PyPI implementation in April 2018.

您需要:

• 确保 setuptools 已升级到版本 38.6.0 或更新版本

• Make sure setuptools is upgraded to version 38.6.0 or newer

确保 twine 已升级到 1.11 版.0 或更新版本

Make sure twine is upgraded to version 1.11.0 or newer

确保 wheel 已升级到 0.31 版.0 或更新版本

Make sure wheel is upgraded to version 0.31.0 or newer

向您的 setup() 调用添加一个名为 long_description_content_type 的新字段，并将其设置为 'text/markdown':

Add a new field named long_description_content_type to your setup() call, and set it to '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:

Use twine to upload your distributions to PyPI:

$ python setup.py sdist bdist_wheel   # adjust as needed
$ twine upload dist/*

旧的 PyPI 基础架构不会呈现 Markdown，只有新的 Warehouse 基础架构可以.遗留基础架构现已消失(截至 2018-04-30).

The old legacy PyPI infrastructure would not render Markdown, only the new Warehouse infrastructure does. The legacy infrastructure is now gone (as of 2018-04-30).

目前，PyPI 使用 cmarkgfm 作为降价渲染器，通过 readme_renderer 库(使用 readme_renderer.markdown.render(long_description)code> 以生成 HTML 输出).这意味着您的 Markdown 文档将呈现与在 GitHub 上完全相同；它本质上是相同的渲染器.

Currently, PyPI uses cmarkgfm as the markdown renderer, via the readme_renderer library (using readme_renderer.markdown.render(long_description) to produce HTML output). This means that your markdown documents will render exactly the same as on GitHub; it is essentially the same renderer.

您可以使用 twine check 命令(twine 1.12.0 或更新版本).

You can validate your package long_description with the twine check command (twine 1.12.0 or newer).

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

The old < 2018-03-16 answer follows below.

注意:这是旧的、现已过时的答案，截至 2018 年 3 月 16 日，如果您使用正确的工具，则支持 Markdown，请参见上文.

PyPI不支持 Markdown，所以你的 README 不会被渲染成 HTML.

PyPI does not support Markdown, so your README will not be rendered into HTML.

如果你想要一个渲染的自述文件，坚持使用 reStructuredText；Sphinx 对 reStructuredText 的介绍 是一个很好的起点.

If you want a rendered README, stick with reStructuredText; the Sphinx introduction to reStructuredText is a good starting point.

您可能想要安装 docutils 包，以便您可以在本地测试您的文档；您想在自述文件中运行包含的 rst2html.py 脚本以查看产生的错误(如果有).您的特定示例有太多错误:

You probably want to install the docutils package so you can test your document locally; you want to run the included rst2html.py script on your README to see what errors are produced, if any. Your specific sample has too many errors:

$ 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 代码块(可能，如果 docutils 的 PyPI 版本足够新):

Your code block is using Github's Markdown extensions, which are entirely wrong for reStructuredText. You could use a reST code block (probably, if the PyPI version of docutils is new enough):

.. code-block:: python

    @attr(section='MySection', type='functional+', module='MyModule', id=1)
    def test_function(self):
        """
        This is the original docstring
        """
        pass

要在本地进行测试，您还需要安装 Pygments.

To test this locally you'll need to install Pygments as well.

有一个带有拉取请求的功能请求来添加对 Markdown 的支持，如果你有兴趣.

There is a feature request with pull request to add support for Markdown, if you are interested.

这篇关于如何使 PyPi 描述 Markdown 工作?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！