Extension README pour les projets Python

Question

Les outils de packaging Python s’attendent à ce que notre fichier readme soit nommé README ou README.txt. Mais si nous suivons cette convention, GitHub l’affiche sous forme de texte brut dans la page du projet, ce qui n’est pas beau. (contrairement à la belle version HTML nommée README.rst)

Existe-t-il une technique pour rendre PyPI et GitHub heureux à propos de README?

Answer 1

PyPI n'exige pas que le fichier s'appelle README ou README.txt, appelez-le simplement README.rst. En fait, PyPI ne regardera pas du tout dans votre paquet (bien que je puisse me tromper là-dedans, je n’ai pas étudié le code), le texte qui se termine au premier plan est le long_description paramètre.

Ensuite, dans votre setup.py, vous faites quelque chose comme ceci:

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

Answer 2

Une façon grossière à laquelle je peux penser est de faire un lien symbolique vers README appelé README.rst et de les vérifier tous les deux.

Answer 3

Vous pouvez utiliser un git pilote de filtre , ce qui serait, à la caisse, prendre votre README.md (nécessaire par GitHub) et de générer un bon README (nécessaire par Python)

Toutefois, toute modification de ce fichier privé README doit être signalé manuellement à l' README.md le fichier (au moins en raison de la syntaxe markdown qui aucun script peut deviner pour vous)

C'est pourquoi Noufal Ibrahim's réponse (que je upvoted) pourrait être plus adaptée, surtout si vous avez accès à des liens symboliques (je suis encore avec Windows Xp au travail, donc pas de chance pour moi):

Avoir faire README être un lien symbolique vers README.rst, ou, comme Arto Bendiken commentaires:
=> avoir README.rst être un lien symbolique ro README.

Git stocke le lien symbolique (et non pas le fichier, le lien fait référence à), de sorte que vous pouvez avoir à la fois README et son README.rst le fichier dans votre repo Git.

Answer 4

Citant Éric Araujo au Python bug sur la distutils avertissement:

Dans l'emballage/distutils2, le langage ressemble à ceci (dans la configuration.cfg):

[metadata]
description-file = README.whatever

sdist comprendra que fichier. Vous pouvez également écrire la description dans le programme d'installation.cfg directement et avoir votre fichier README fourni avec le extra_files champ.

Donc, en gros, ignorer l'avertissement à partir d' distutils manque un README.txt. Aussi, distutils2 soi-disant ne pas émettre de cet avertissement (je n'ai pas testé), donc vous pouvez essayer la mise à niveau.

Answer 5

En plus (non-distutils2) des configurations, vous pouvez ajouter votre README.rst de la MANIFEST.in le fichier explicitement. Vous aurez toujours de voir un avertissement à propos de la norme README{.txt} étant absent, mais votre fichier README.tvd sera inclus dans votre sdist tarball, sens, il sera inclus pour les utilisateurs qui ont téléchargé directement à partir de PIPY.

Voir http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template pour plus de détails.