Расширение README для проектов Python

Question

Инструменты упаковки Python ожидают, что наш файл readme должен иметь имя README или README.txt. Но если мы будем следовать этому соглашению, GitHub отобразит его как обычный текст на странице проекта, что не очень красиво. (в отличие от прекрасной HTML-версии, названной README.rst)

Есть ли какая-нибудь техника, которая бы порадовала и PyPI, и GitHub в README.

Answer 1

PyPI не требует, чтобы файл назывался README или README.txt, поэтому просто назовите его README.rst.На самом деле, PyPI не будет, насколько я знаю, вообще заглядывать в ваш пакет (хотя я могу ошибаться там, я не изучал код или что-то в этом роде), текст, который заканчивается впереди, - long_description параметр.

Затем в вашем файле setup.py вы делаете что-то вроде этого:

setup(name='Your module name',
      version="1.0",
      description="Whatever, dude.",
      long_description=open('docs/README.rst', 'rt').read()
)

Answer 2

Грубый способ, который я могу придумать, состоит в том, чтобы создать символическую ссылку на README, называемую README.rst, и проверить их оба.

Answer 3

Вы можете использовать драйвер фильтра git , который при оформлении заказа возьмет ваш README.md (необходимый для GitHub) и сгенерирует правильный README (необходимый для Python, хотя Lennart Regebro * ответ предполагает, что PyPI не требует какой-либо файл README)

Итак, оставив в стороне тот факт, что PyPI не нуждается в README (а предупреждение можно просто игнорировать), вот как можно (в общем случае) сгенерировать ожидаемый файл с помощью Git:

Однако о любом изменении этого закрытого файла README необходимо сообщать вручную в файл README.md (по крайней мере, из-за синтаксиса уценки, который ни один сценарий не может угадать для вас)

Вот почему Noufal Ibrahim answer (за который я проголосовал) может быть более адаптировано, особенно если у вас есть доступ к символическим ссылкам (я все еще работаю с Windows Xp, так что не повезло мне):

Если сделать README символической ссылкой на README.rst, или, как Арто Бендикен , комментарии:
=> с README.rst символической ссылкой ro README.

Git будет хранить символическую ссылку (и не файл, на который ссылается символическая ссылка ), поэтому вы можете иметь как README, так и его README.rst файл в репозитории Git.

Answer 4

Цитата Эрика Араужо об ошибке Python о предупреждении distutils :

В упаковке / distutils2 рекомендуемая идиома выглядит следующим образом (в setup.cfg):

[metadata]
description-file = README.whatever

sdist будет включать этот файл.Вы также можете написать описание в файле setup.cfg напрямую и включить свой файл README в поле extra_files.

Так что, по сути, игнорируйте предупреждение от distutils о пропущенном README.txt.Кроме того, distutils2 предположительно не выдает это предупреждение (я не проверял), поэтому вы можете попробовать обновить.

Answer 5

В старых (не distutils2) настройках вы можете явно добавить ваш README.rst в файл MANIFEST.in. Вы по-прежнему будете видеть предупреждение об отсутствии стандартного файла README {.txt}, но ваш файл README.rst будет включен в ваш архив sdist, что означает, что он будет включен для конечных пользователей, которые скачивают напрямую из PIPY.

Подробнее см. http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template.