python - tutorial - md docs

Extensión README para proyectos Python

Question

Las herramientas de empaquetado de Python esperan que nuestro archivo Léame se llame README o README.txt. Pero si seguimos esta convención, GitHub la muestra como texto sin formato en la página del proyecto, que no es bonita. (a diferencia de la hermosa versión HTML cuando se nombra como README.rst)

¿Hay alguna técnica para hacer felices tanto a PyPI como a GitHub acerca de README?

Answer 1

Citando a Éric Araujo en el bugs.python.org/issue11913 :

En packaging / distutils2, la expresión recomendada se ve así (en setup.cfg):

[metadata]
description-file = README.whatever

sdist incluirá ese archivo. También puede escribir la descripción en setup.cfg directamente y tener su archivo README incluido con el campo extra_files.

Entonces, básicamente, ignore la advertencia de distutils acerca de un distutils README.txt falta. Además, distutils2 supuestamente no emite esta advertencia (no lo he probado), por lo que podría intentar actualizar.

Answer 2

En configuraciones anteriores (sin distutils2 ), puede agregar su README.rst al archivo MANIFEST.in explícitamente. Todavía verá una advertencia sobre la ausencia del archivo README estándar .txt, pero su README.rst se incluirá en su tarball sdist, lo que significa que se incluirá para los usuarios finales que descarguen directamente desde PIPY.

Ver http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template para más detalles.

Answer 3

Podrías usar un controlador de filtro git que, en el proceso de compra, tomaría tu README.md (necesario por GitHub) y generaría un README adecuado (necesario por Python, aunque la answer Lennart Regebro sugiere que PyPI no requiere ningún archivo README)

Por lo tanto, dejando de lado el hecho de que PyPI no necesita un README (y la advertencia podría simplemente ignorarse), aquí es cómo podría (en general) generar el archivo esperado con Git:

Sin embargo, cualquier modificación de ese archivo privado README tendría que informarse manualmente en el archivo README.md (al menos debido a la sintaxis de rebajas que ningún script puede adivinar).

Es por eso que la answer Noufal Ibrahim (que subí) podría ser más adecuada, especialmente si tienes acceso a enlaces simbólicos (todavía estoy trabajando con Windows Xp, así que no tuve suerte):

README.rst que README sea ​​un enlace simbólico a README.rst , o, como comenta Arto Bendiken :
=> teniendo README.rst como un enlace simbólico para README .

Git almacenará el enlace simbólico (y no el archivo al que hace referencia el enlace simbólico ), por lo que puede tener tanto el archivo README como el archivo README.rst en su repositorio Git.

Answer 4

PyPI no tiene ningún requisito de que el archivo se llame README o README.txt, así que simplemente llámalo README.rst. De hecho, PyPI no verá nada en mi paquete (aunque podría estar equivocado allí, no he estudiado el código ni nada), el texto que termina en el frente es el parámetro long_description .

Luego, en su setup.py, haga algo como esto:

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

Answer 5

Una forma cruda en la que puedo pensar es hacer un enlace simbólico a README llamado README.rst y verificar ambos en.