PyPi 설명 마크 다운을 작동시키는 방법은 무엇입니까?

PyPi 설명 마크 다운을 작동시키는 방법은 무엇입니까?

---

다음을 사용하여 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 일명 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 를 통해 마크 다운 렌더러로 사용 합니다 ( HTML 출력 생성에 사용 ). 이는 마크 다운 문서가 GitHub 에서와 똑같이 렌더링된다는 것을 의미합니다 . 본질적으로 동일한 렌더러입니다.readme_rendererreadme_renderer.markdown.render(long_description)

당신은 당신의 패키지를 확인할 수 long_description와 twine check명령 ( twine1.12.0 이상).

이전 <2018-03-16 답변은 다음과 같습니다.

---

참고 : 이것은 2018 년 3 월 16 일부터 올바른 도구를 사용하는 경우 Markdown이 지원됩니다 . 위를 참조하세요 .

PyPI는 Markdown을 지원 하지 않으므로 README는 HTML로 렌더링되지 않습니다.

렌더링 된 README를 원한다면 reStructuredText를 사용하십시오. reStructuredText에 대한 Sphinx 소개 는 좋은 출발점입니다.

로컬에서 문서를 테스트 할 수 있도록 docutils패키지 를 설치하고 싶을 것입니다 . rst2html.pyREADME에 포함 된 스크립트 를 실행하여 어떤 오류가 생성되는지 확인하려고합니다. 특정 샘플에 너무 많은 오류가 있습니다.

$ 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에 대한 지원을 추가하기위한 풀 요청 이있는 기능 요청이 있습니다.

---

으로 @Martijn Pieters언급, PyPi는 마크 다운을 지원하지 않습니다. 나는 다음과 같은 트릭을 배운 곳 잘 모르겠어요,하지만 당신은 사용할 수 있습니다 Pandoc 및 PyPandoc을 에 업로드하기 전에 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,
)

To install Pandoc on OS X, I used Homebrew:

brew install pandoc

To install PyPandoc, I used pip:

pip install pypandoc

---

PyPI supports rst and not markdown as mentioned on other answers. But you don't need pypandoc perse, just pandoc is fine. You can generate the rst file locally first and then run setup.py to upload the package.

upload.sh:

#!/bin/bash
pandoc --from=markdown --to=rst --output=README README.md
python setup.py sdist upload

The generated file named README will be automatically recognized. Be sure to add it to your .gitignore! The setup.py doesn't have to do anything special.

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=[],
)

Then just run bash upload.sh to upload the stuff to PyPI.

---

I've had issues with \r characters causing parsing issues where only the first line of the README appears in pypi. The code below fixes the issue, it comes from the pypandoc module repository:

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()

This way long_description contains a sanitized version of your Readme and you can pass it to the setup() function in your setup.py script.

---

There is a good pip package that worked for me

https://pypi.python.org/pypi/restructuredtext_lint/

I'm using it on my setup now:

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)

Also I have created a lib to be able to use in py.test later

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

---

You can set markdown in setup.cfg file too:

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

Checkout my project as an example: on github and on pypi.

ReferenceURL : https://stackoverflow.com/questions/26737222/how-to-make-pypi-description-markdown-work