web-dev-qa-db-ja.com

PyPi description Markdownを機能させる方法は？

以下を使用してパッケージを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
```

ただし、テキストはそのまま表示されます、マークダウンフォーマットなし。私は何を間違えていますか？

pythonrestructuredtextpypi
52
Maroun

2018年3月16日の時点で、PyPI.org別名Warehouse（最終的に）は、長い説明でマークダウンをサポートしています。 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 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は _readme_renderer_ library を介して cmarkgfm をマークダウンレンダラーとして使用します（readme_renderer.markdown.render(long_description)を使用してHTML出力を生成します）。これは、マークダウンドキュメントが GitHubとまったく同じをレンダリングすることを意味します。基本的に同じレンダラーです。

パッケージ_long_description_を検証するには、 _twine check_コマンド （twine 1.12.0以降）を使用します。

以前の<2018-03-16の回答は以下のとおりです。

注：これは古い、今では時代遅れの回答です。2018-03-16現在、適切なツールを使用すればMarkdownがサポートされています。上記を参照してください。

PyPIはMarkdownを not サポートしているため、READMEはHTMLにレンダリングされません。

レンダリングされたREADMEが必要な場合は、reStructuredTextを使用してください。 reStructuredTextのスフィンクス入門 が出発点として適しています。

ドキュメントをローカルでテストできるように、おそらく docutils package をインストールする必要があります。含まれている_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コードブロックを使用できます（おそらく、docutilsのPyPIバージョンが十分に新しい場合）。

_.. code-block:: python

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

これをローカルでテストするには、 Pygments もインストールする必要があります。

興味がある場合は、Markdownのサポートを追加する プルリクエスト付きの機能リクエスト があります。

89
Martijn Pieters

@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
56
Matthew Rankin

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にアップロードします。

14
Chiel ten Brinke

\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にはReadmeのサニタイズバージョンが含まれており、setup.pyスクリプトのsetup（）関数に渡すことができます。

4
Overdrivr

私のために働いた良いピップパッケージがあります

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
3
Pablo Daniel Estigarribia Davy