python - language - sphinx documentation wikipedia

Descripción de PyPi markdown no funciona

Question

Subí un paquete a PyPi usando:

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

Estoy tratando de modificar la descripción, escribí (por favor, no edite el formato del siguiente fragmento de código, lo hice con el propósito de demostrar mi problema):

**nose-docstring-plugin**

This plugin enables you to modify docstring of tests based on their attributes, for example:
```python
@attr(section=''MySection'', type=''functional+'', module=''MyModule'', id=1)
def test_function(self):
    """
    This is the original docstring
    """
    pass
```

Sin embargo, el texto aparece como está, sin el formato de reducción. ¿Qué estoy haciendo mal?

Answer 1

A partir del 16 de marzo de 2018, PyPI.org aka Warehouse (finalmente) admite Markdown en descripciones largas. Warehouse reemplazó la antigua implementación PyPI heredada en abril de 2018.

Necesitas:

• Asegúrese de que setuptools se actualice a la versión 38.6.0 o más reciente

• Asegúrese de que el twine esté actualizado a la versión 1.11.0 o más reciente

• Asegúrate de que la wheel esté actualizada a la versión 0.31.0 o más reciente

• Agregue un nuevo campo llamado long_description_content_type a su llamada a setup() , y long_description_content_type en ''text/markdown'' :

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

  Consulte PEP 566 - Metadatos para paquetes de software de Python 2.1 .

• Use twine para subir sus distribuciones a PyPI:

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

La antigua infraestructura PyPI heredada no generaría Markdown, solo la nueva infraestructura de Warehouse. La infraestructura heredada ya no existe (a partir de 2018-04-30).

Actualmente, PyPI usa cmarkgfm como el procesador de readme_renderer , a través de la biblioteca readme_renderer (mediante el uso de readme_renderer.markdown.render(long_description) para producir un resultado HTML). Esto significa que sus documentos de rebaja se mostrarán exactamente igual que en GitHub; Es esencialmente el mismo renderizador.

Puede validar su paquete long_description con el comando twine check ( twine 1.12.0 o más reciente).

La respuesta anterior <2018-03-16 sigue a continuación.

Nota: esta es la respuesta antigua, ahora desactualizada, a partir de 2018-03-16 Markdown es compatible siempre que use las herramientas adecuadas, consulte más arriba .

PyPI no admite Markdown, por lo que su README no se procesará en HTML.

Si quieres un README renderizado, quédate con reStructuredText; La introducción de Sphinx a reStructuredText es un buen punto de partida.

Probablemente desee instalar el paquete docutils para poder probar su documento localmente; desea ejecutar el script rst2html.py incluido en su README para ver qué errores se producen, si los hay. Su muestra específica tiene demasiados errores:

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

Su bloque de código está utilizando las extensiones Markdown de Github, que son totalmente incorrectas para reStructuredText. Podría usar un bloque de código reST (probablemente, si la versión PyPI de docutils es lo suficientemente nueva):

.. code-block:: python

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

Para probar esto localmente necesitarás instalar Pygments también.

Hay una solicitud de función con solicitud de extracción para agregar soporte para Markdown, si está interesado.

Answer 2

Como @Martijn Pieters , PyPi no es compatible con Markdown. No estoy seguro de dónde aprendí el siguiente truco, pero puede usar PyPandoc y PyPandoc para convertir sus archivos de Markdown en texto reestructurado antes de subirlos a PyPi . Para lograr esto, agregue lo siguiente a su archivo setup.py :

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

Para instalar Pandoc en OS X, usé Homebrew :

brew install pandoc

Para instalar PyPandoc , utilicé pip :

pip install pypandoc

Answer 3

Ejecuta estos tres comandos y funcionará

pip install --upgrade setuptools
pip install --upgrade twine
pip install --upgrade wheel

Answer 4

Hay un buen paquete de pip que funcionó para mí

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

Lo estoy usando en mi configuración ahora:

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)

También he creado una lib para poder usar en py.test más tarde

https://github.com/pablodav/burp_server_reports/blob/master/burp_reports/lib/check_readme.py

Answer 5

He tenido problemas con los caracteres que causan problemas de análisis en los que solo aparece la primera línea de README en pypi. El siguiente código soluciona el problema, proviene del repositorio de módulos 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()

De esta manera, long_description contiene una versión desinfectada de su archivo Léame y puede pasarla a la función setup () en su script setup.py .

Answer 6

PyPI admite rst y no markdown como se menciona en otras respuestas. Pero no necesitas pypandoc perse, solo pandoc está bien. Puede generar el primer archivo local primero y luego ejecutar setup.py para cargar el paquete.

upload.sh :

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

El archivo generado llamado README será reconocido automáticamente. ¡Asegúrese de agregarlo a su .gitignore ! El setup.py no tiene que hacer nada especial.

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

Luego simplemente ejecuta bash upload.sh para cargar las cosas en PyPI.