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)Extensión README para proyectos Python
¿Hay alguna técnica para hacer que tanto PyPI como GitHub estén contentos con respecto a README?
Se puede usar un git filter driver que, a la salida, tome su README.md (necesario para GitHub) y generar una adecuada README (necesario para Python, aunque Lennart Regebro 's answer sugiere que PyPI hace no requiere ningún archivo README)
por lo tanto, mantener a un lado el hecho de que PyPI no necesita un README (y la advertencia podría ser simplemente ignorado), aquí es cómo se puede (en general) generar el archivo de espera con Git:
Sin embargo, tendría que ser informado de forma manual en el fichero de README.md (al menos a causa de la sintaxis de reducción del precio que ningún script puede adivinar por ti)
Eso es cualquier modificación a ese archivo privado README qué Noufal Ibrahim 's answer (que me upvoted) podría ser más adecuado, especialmente si usted tiene acceso a enlaces simbólicos (todavía estoy con Windows XP en el trabajo, por lo que no hubo suerte para mí):
tiene compone README ser un enlace simbólico a README.rst, o, como Arto Bendiken comentarios :
=>teniendo README.rst siendo un enlace simbólico ro README.
Git almacenará el enlace simbólico (y not the file the symlink refers to), lo que puede tener tanto README y su archivo README.rst en tu repositorio Git.
Una forma cruda que se me ocurre es hacer un enlace simbólico a README llamada README.rst y comprobar que tanto en.
Esto es lo que hago, aunque al revés: el 'README' es un enlace simbólico a' README.rst' (o 'README.md', para proyectos que no son de Python). –
Eso también funciona. –
+1, buen punto, aunque el estilo de @ Arto también tiene sentido. He incluido esto en mi respuesta, con un enlace y un voto alternativo a su respuesta. – VonC
PyPI no tiene ningún requisito de que el archivo se llama README o LEEME.txt, por lo que sólo lo llaman README .rst. De hecho, PyPI no verá nada en mi paquete (aunque podría estar equivocado, 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, que hacer algo como esto:
setup(name='Your module name',
version="1.0",
description="Whatever, dude.",
long_description=open('docs/README.rst', 'rt').read()
)
Lennart tiene razón. PyPI puede analizar reST en long_description, no usa README. La advertencia es solo una advertencia; nombra tu archivo README o ignora la advertencia. packaging/distutils2 es más inteligente; ver el informe de errores para más información. –
Citando Éric Araujo en el Python bug about the distutils warning:
en el empaquetado/distutils2, el idioma recomendado es similar a esto (en setup.cfg):
[metadata] description-file = README.whateversdist 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.
Así que, básicamente, hacer caso omiso de la advertencia de distutils por perder un README.txt. Además, distutils2 supuestamente no emite esta advertencia (no lo he probado), por lo que podría intentar actualizar.
En las configuraciones anteriores (no 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.
Consulte http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template para obtener más información.
PyPI * no * espera que el archivo se denomine README o README.txt. No sé a qué herramientas de empaquetado Python te refieres, pero no conozco ninguna que requiera esta denominación, y si lo hace, es probable que se solucione fácilmente. –
Lennart, cuando ejecuto 'setup.py sdist' sin un archivo README, dice' warning: sdist: archivo estándar no encontrado: debería tener uno de README, README.txt' ... pero supongo que esto es solo una queja que puedo ¿ignorar? – rescdsk
@rescdsk: Sí, puedes ignorarlo. AFAIK no hay nada que use eso. De hecho, eso realmente debería enviarse como un informe de error. –