web-dev-qa-db-fra.com

Comment faire fonctionner Markdown de description PyPi?

J'ai téléchargé un package sur PyPi en utilisant:

python setup.py register -r pypi
python setup.py sdist upload -r pypi

J'essaie de modifier la description, j'ai écrit (veuillez ne pas modifier le formatage du morceau de code suivant, je l'ai fait exprès pour démontrer mon problème):

**my plugin**

This plugin enables you to ... For example:
```python
@attr(section='MySection', id=1)
def test_function(self):
    """
    Bla bla bla
    """
    pass
```

Cependant, le texte apparaît tel quel, sans la mise en forme de démarque. Qu'est-ce que je fais mal?

pythonrestructuredtextpypi
52
Maroun

Depuis le 16 mars 2018, PyPI.org aka Warehouse (enfin) prend en charge Markdown dans les longues descriptions. Warehouse a remplacé l'ancienne implémentation PyPI héritée en avril 2018.

Tu dois:

  • Assurez-vous que setuptools est mis à niveau vers la version 38.6.0 ou plus récente

  • Assurez-vous que twine est mis à niveau vers la version 1.11.0 ou plus récente

  • Assurez-vous que wheel est mis à niveau vers la version 0.31.0 ou plus récente

  • Ajoutez un nouveau champ nommé long_description_content_type À votre appel setup() et définissez-le sur 'text/markdown':

    setup(
    long_description="""# Markdown supported!\n\n* Cheer\n* Celebrate\n""",
    long_description_content_type='text/markdown',
    # ....
)

    Voir PEP 566 - Métadonnées pour Python Packages logiciels 2.1 .

  • Utilisez twine pour télécharger vos distributions sur PyPI:

    $ python setup.py sdist bdist_wheel   # adjust as needed
$ twine upload dist/*

L'ancienne infrastructure PyPI héritée ne rendrait pas Markdown, seule la nouvelle infrastructure Warehouse le fait. L'infrastructure héritée a maintenant disparu (au 30/04/2018).

Actuellement, PyPI utilise cmarkgfm comme rendu de démarque, via la bibliothèque readme_renderer (en utilisant readme_renderer.markdown.render(long_description) pour produire du HTML production). Cela signifie que vos documents de démarque rendront exactement les mêmes que sur GitHub; c'est essentiellement le même moteur de rendu.

Vous pouvez valider votre package long_description Avec la commande twine check (twine 1.12.0 ou plus récent).

L'ancienne réponse <2018-03-16 suit ci-dessous.

Remarque: il s'agit de l'ancienne réponse, désormais obsolète, à partir du 16/03/2018, Markdown est pris en charge à condition d'utiliser les bons outils, voir ci-dessus .

PyPI ne prend pas en charge Markdown, donc votre README ne sera pas rendu en HTML.

Si vous voulez un README rendu, restez avec reStructuredText; l'introduction de Sphinx à reStructuredText est un bon point de départ.

Vous voudrez probablement installer le docutils package pour pouvoir tester votre document localement; vous voulez exécuter le script rst2html.py inclus sur votre README pour voir quelles erreurs sont produites, le cas échéant. Votre échantillon spécifique contient trop d'erreurs:

$ 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.

Votre bloc de code utilise les extensions Markdown de Github, qui sont totalement incorrectes pour reStructuredText. Vous pouvez utiliser un bloc de code reST (probablement, si la version PyPI de docutils est suffisamment nouvelle):

.. code-block:: python

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

Pour tester cela localement, vous devrez également installer Pygments .

Il y a demande de fonctionnalité avec demande de pull pour ajouter le support de Markdown, si vous êtes intéressé.

89
Martijn Pieters

Comme @Martijn Pieters a déclaré, PyPi ne prend pas en charge Markdown. Je ne sais pas où j'ai appris l'astuce suivante, mais vous pouvez utiliser Pandoc et PyPandoc pour convertir vos fichiers Markdown en RestructuredText avant de les télécharger dans PyPi =. Pour ce faire, ajoutez ce qui suit à votre setup.py fichier:

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,
)

Pour installer Pandoc sur OS X, j'ai utilisé Homebrew :

brew install pandoc

Pour installer PyPandoc , j'ai utilisé pip :

pip install pypandoc
56
Matthew Rankin

PyPI prend en charge la première et non la démarque comme mentionné dans les autres réponses. Mais vous n'avez pas besoin de pypandoc perse, juste pandoc c'est bien. Vous pouvez d'abord générer le premier fichier localement, puis exécuter setup.py pour télécharger le package.

upload.sh:

#!/bin/bash
pandoc --from=markdown --to=rst --output=README README.md
python setup.py sdist upload

Le fichier généré nommé README sera automatiquement reconnu. Assurez-vous de l'ajouter à votre .gitignore! Le setup.py n'a rien à faire de spécial.

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=[],
)

Ensuite, exécutez simplement bash upload.sh pour télécharger le contenu sur PyPI.

14
Chiel ten Brinke

J'ai rencontré des problèmes avec \r caractères provoquant des problèmes d'analyse où seule la première ligne du README apparaît dans pypi. Le code ci-dessous corrige le problème, il provient du référentiel du module 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()

Par ici long_description contient une version filtrée de votre fichier Lisez-moi et vous pouvez la transmettre à la fonction setup () dans votre setup.py script.

4
Overdrivr

Il y a un bon paquet pip qui a fonctionné pour moi

https://pypi.python.org/pypi/restructuredtext_lint/

Je l'utilise sur ma configuration maintenant:

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)

J'ai également créé une bibliothèque pour pouvoir l'utiliser dans py.test plus tard

https://github.com/pablodav/burp_server_reports/blob/master/burp_reports/lib/check_readme.py
3
Pablo Daniel Estigarribia Davy