Как заставить работать описание PyPi Markdown?

Ответ 1

С 16 марта 2018 года PyPI.org или Warehouse (наконец-то) поддерживает Markdown в длинных описаниях. Склад заменил старое устаревшее внедрение PyPI в апреле 2018 года.

Вам нужно:

• Убедитесь, что 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 (используя readme_renderer.markdown.render(long_description) для создания вывода в формате HTML). Это означает, что ваши документы уценки будут отображаться точно так же, как на GitHub; это по сути тот же рендер.

Вы можете проверить ваш пакет long_description с помощью команды twine check twine (twine 1.12.0 или новее).

Старый ответ <2018-03-16 следует ниже.

Примечание: это старый, ныне устаревший ответ, по состоянию на 2018-03-16 поддерживается уценка при условии, что вы используете правильные инструменты, см. Выше.

PyPI не поддерживает Markdown, поэтому ваш README не будет отображаться в HTML.

Если вы хотите получить README, используйте reStructuredText; введение Сфинкса в 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 (возможно, если Python-версия Docutils достаточно новая):

.. code-block:: python

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

Чтобы проверить это локально, вам также нужно установить Pygments.

Если вам интересно, есть функция запроса с запросом на добавление для добавления поддержки Markdown.

Ответ 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,
)

Чтобы установить Pandoc на OS X, я использовал Homebrew:

brew install pandoc

Чтобы установить PyPandoc, я использовал pip:

pip install pypandoc

Ответ 3

PyPI поддерживает первую, а не уценку, как упоминалось в других ответах. Но вам не нужно 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.

Ответ 4

У меня были проблемы с символами \r, вызывающими проблемы с синтаксическим разбором, когда в pypi появляется только первая строка README. В приведенном ниже коде устранена проблема, она поступает из репозитория модуля 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() в setup.py script.

Ответ 5

Есть хороший пакет для папок, который работал у меня

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)

Также я создал lib для возможности использования в py.test позже

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

Ответ 6

Вы также можете установить уценку в файле setup.cfg:

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

Оформите мой проект в качестве примера: на github и на pypi.