Readthedocs.org: Poesía de apoyo

¿Cuál sería el flujo de trabajo de poesía al leer los documentos? El soporte de Pipfile saldrá pronto por cierto. Si esto se implementa, viviría como una opción en el archivo de configuración.

localmente ejecuto poetry install para crear un virtualenv e instalar las dependencias, luego poetry run sphinx-build ... para ejecutar sphinx-build dentro de ese virtualenv.

aunque si ya hay un virtualenv activo, entonces la poesía instalará las dependencias en ese en su lugar, lo que significa que debería funcionar igual que para requirements.txt o Pipfile?

Mi flujo de trabajo es bastante similar:

1. poetry install , que instala las dependencias dev y prod de forma predeterminada
2. cd docs , paso opcional
3. poetry run make html , para construir el sitio web estático

Ejemplo de proyecto real que usa poetry y rtd : https://github.com/wemake-services/wemake-django-template

Entonces, reemplazar el paso pip install por poetry install es todo lo que se necesita aquí o hay más trucos que no veo?

@humitos sí, eso creo.

Tenga en cuenta que también tenemos que trabajar con venv diferente: necesitamos prefijar todos los comandos con poetry run .

si tiene el venv activo, puede ejecutar poetry install y se instalará en el entorno actual de la misma manera que lo hará pip install -r requirements.txt , luego puede usar el venv como lo haría normalmente.

poetry run es solo una abreviatura para ejecutar cosas en el venv sin tener que recordar dónde está o activarlo primero.

dependencias dev y prod

¿Existe un caso de uso en el que los usuarios solo quieran instalar dev / prod deps? ¿Hay otras configuraciones que los usuarios deseen establecer?

poetry install instalará tanto las dependencias de desarrollo como las regulares
poetry install --no-dev instalará solo dependencias regulares y no cosas de desarrollo

el último es más en la línea de setup.py install con la advertencia de que no instalará el módulo en sí, no puedo pensar en una razón en la parte superior de mi cabeza para no instalar dependencias de desarrollo para la generación de documentos ...

también puede usar poetry install --extras "foo bar" para instalar grupos de dependencia adicionales foo y bar

los documentos completos están en https://poetry.eustace.io/docs/cli/#install

Creo que este problema se resolverá solo una vez que se publique la próxima versión de pip con soporte PEP-517 (¿escuché en enero de 2019?). Se fusionó: https://github.com/pypa/pip/pull/5743
Entonces, un proyecto solo necesita agregar

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

al pyproject.toml , y el pip install normal debería funcionar.

excepto que el script de compilación ejecuta python setup.py install --force por defecto en lugar de pip install . entonces pep-517 no entrará en juego?

@danielknell apoyamos la instalación del proyecto usando pip.

@uSpike He leído el problema de pip y pep, pero todavía no pude entenderlo muy bien: / ¿reemplazará esto también a pipenv?

@stsewd pip podría instalarse desde Pipfile en algún momento en el futuro, pero AFAIK no está en la hoja de ruta en el corto plazo.

@danielknell - sí, verifique aquí: https://docs.readthedocs.io/en/latest/yaml-config.html#python -pip-install, también podría hacerlo a través de la configuración web. Entonces, supongo que solo estamos esperando https://github.com/pypa/pip/issues/6106. @stsewd : una vez que pip 0.19.0 sale, ¿cuánto tiempo antes de que se convierta en una imagen de readthedocs que podamos usar?

Instalamos la última versión de pip antes de cada compilación # 4938, por lo que debería estar disponible después de que la publiquen :)

No estoy muy familiarizado con los entornos virtuales de Python, pero puede haber otro problema allí.

Ejecuto poesía desde un script conf.py , pero obtengo el siguiente error, que no veo cómo podría solucionarse desde el lado del usuario:

Creating virtualenv clang-api-doc-py3.5 in /home/docs/.cache/pypoetry/virtualenvs
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt-get install python3-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Failing command: ['/home/docs/.cache/pypoetry/virtualenvs/clang-api-doc-py3.5/bin/python', '-Im', 'ensurepip', '--upgrade', '--default-pip']

https://github.com/pypa/pip/issues/6106#issuecomment -456528521

Dado que se lanzó el nuevo pip@19 , aquí está una breve descripción de lo que está sucediendo.
He comprobado localmente cómo funciona pip@19 con dos configuraciones:

1. Aplicación: https://github.com/wemake-services/wemake-django-template
2. Biblioteca: https://github.com/wemake-services/wemake-python-styleguide

Solicitud

Intentando: pip install .
Resultado:

`` `" No se encontró ningún archivo / carpeta para el paquete {} ". Formato (nombre)
poetry.masonry.utils.module.ModuleOrPackageNotFound: No se encontró ningún archivo / carpeta para el paquete wemake-django-template

----------------------------------------

Comando "/Users/sobolev/Documents/github/wemake-django-template/.venv/bin/python3 /Users/sobolev/Documents/github/wemake-django-template/.venv/lib/python3.6/site-ages /pip/_vendor/pep517/_in_process.py prepare_metadata_for_build_wheel / var / carpetas / qn / 2gssw9hx48g81chw0398hlrr0000gn / T / tmpbzmmkx48 "falló con el código de error 1 en / private / var / carpetas / qn / 2gb48 / pgswch9h039
''

Biblioteca

Intentando: pip install .
Resultado: instala todo como debería.

¿Funciona dentro de rtfd? Sigo con la intención de intentarlo, pero aún no he encontrado tiempo para actualizar mis proyectos con la configuración para instalar a través de pip.

@sobolevn No esperaría que https://github.com/wemake-services/wemake-django-template se instale ya que es un proyecto de plantilla (cortador de galletas).

@uSpike poetry install funciona, así que esperaba que pip install también funcionara.

poetry install solo instalará las dependencias dev / prod, no el módulo en sí
pip install . intentará instalar el módulo en sí, y con él las dependencias de prod.

el hecho de que no instale dependencias de desarrollo es preocupante y tal vez pep 517 no sea suficiente para respaldar completamente los proyectos de poesía.

poetry install también instala el proyecto en el modo editable. https://github.com/sdispater/poetry/releases/tag/0.12.0

También intenté investigar este problema dev / no-dev , parece que todavía no hay una solución conocida.

eso significa que poetry install es equivalente a pip install -e .

¿Alguien puede probar un proyecto en rtd? Tenemos instalado el último pip, avísenos si hay algo más que hacer por nuestra parte para apoyar la poesía.

@sobolevn ese proyecto (https://github.com/wemake-services/wemake-django-template) es una plantilla, se supone que no debes pip install eso. El equivalente es tener un requirements.txt , pero en su lugar usaron poesía. El proyecto real está dentro de https://github.com/wemake-services/wemake-django-template/tree/master/%7B%7Bcookiecutter.project_name%7D%7D pero debe ejecutar cookiecutter para hacerlo.

@danielknell aah Me olvidé de eso ... ¿podría haber una manera de pasar banderas a la poesía a través de pip?

@uSpike dudoso, pip y el pep en sí no tienen nada en ese sentido, lo cual es comprensible ya que está fuera del alcance de la construcción e instalación desde la fuente ...

parece que para instalar un proyecto con dependencias de desarrollo, la única opción es ejecutar poetry install dentro del virtualenv.

¿Qué configuración debo usar para activar una instalación?
Si verifico la compilación usando setup.py se queja. Si desmarco no lo intentaré
para instalar cualquier cosa.

El jue., 24 ene. 2019 a las 9:27, Daniel Knell ( [email protected] )
escribió:

@uSpike https://github.com/uSpike dudoso, pip y el propio pep
realmente no tengo nada en ese sentido, lo cual es comprensible como
está fuera del alcance de la construcción e instalación desde la fuente ...

parece que instalar un proyecto con dependencias de desarrollo es la única opción
es ejecutar la instalación de poesía dentro del virtualenv.

-
Estás recibiendo esto porque estás suscrito a este hilo.
Responda a este correo electrónico directamente, véalo en GitHub
https://github.com/rtfd/readthedocs.org/issues/4912#issuecomment-457215488 ,
o silenciar el hilo
https://github.com/notifications/unsubscribe-auth/ADdcSmGZO6hcPwZkAol5cbWdimuVNRAhks5vGcLYgaJpZM4Ynph9
.

@danielknell Pensé que PEP-517 incluía algunas banderas para que pip pasara cosas al backend: https://www.python.org/dev/peps/pep-0517/#config -settings

Luego, podrían ser capturados por la poesía en https://github.com/sdispater/poetry/blob/master/poetry/masonry/api.py y cambiar la forma en que se construye el dist, ¿tal vez para incluir dependencias de desarrollo?

@lorinkoz

# .readthedocs.yml
python:
   pip_install: true

la única forma de avanzar que veo en este momento a menos que use vanilla sphinx es definir cualquier cosa que sphinx necesite como dependencias opcionales, luego agregarlas a un grupo de extras, luego usar una configuración como:

build:
    image: latest

python:
    version: 3.6
    pip_install: true
    extra_requirements:
        - docs

https://github.com/sdispater/poetry#extras

@danielknell Estoy de acuerdo, hasta que https://github.com/pypa/pip/issues/5771 esté terminado y la poesía agregue soporte para analizar dicha configuración para incluir dependencias de desarrollo en una compilación.

Comentario breve: pip install -e aún no es compatible sin setup.py .

Recibo el Directory '.' is not installable. File 'setup.py' not found. habitual que me hace pensar que se está pasando -e .

Sí, entiendo que no puedo instalar un proyecto con pip install . sin que sea una biblioteca. Pero, mi pregunta sigue siendo: ¿cómo es posible instalar mis departamentos desde pyproject.toml dentro de rtd?

En otras palabras: ¿cómo es posible reemplazar pip install -r requirements.txt que se ejecuta actualmente con algo como poetry install ?

@sobolevn no poetry install .

@stsewd Veo fallas, aunque el proyecto está configurado para instalarse a través de poesía y se instala bien con pip install .[docs] localmente, todavía falla porque no hay setup.py durante la compilación a pesar de que ambos reportan pip 19.0.1, ¿Hay alguna forma de que pueda estar usando un pip diferente en ese paso o algo así?

ver:

compilación: https://readthedocs.org/projects/twelvefactor/builds/8456552/
código: https://github.com/artisanofcode/python-twelvefactor

Curiosamente este pasado previamente, sin cambios que deberían tener influencia en la instalación:
https://readthedocs.org/projects/twelvefactor/builds/8456164/

diferencia entre los dos: https://github.com/artisanofcode/python-twelvefactor/compare/18b3e2b59765695053945778852e7860dd3cd8c6...cb6e69c70bc58e2c315a63cae7c56ae64c7b60b1

https://github.com/orsinium/poetry-setup se puede usar para generar setup.py y requirements.txt mientras esto sigue siendo un problema.

¿Cuál es el estado de esto? Mis documentos comenzaron a generar bien.

@lorinkoz , ¿puedes compartir tu configuración?

Configuración predeterminada en readthedocs respecto a la instalación. Mi proyecto solo tiene un pyproject.toml . De los registros, RTD no está instalando mis dependencias de desarrollo, pero en mi caso, no son obligatorias para compilar los documentos.

También soy usuario de poetry y si pudiera almacenar todas las dependencias en pyproject.toml , sería feliz.
No estoy seguro de que sea un trabajo de poetry cambiar la forma en que construyen la rueda con la API PEP517; no creo que deban incluir dependencias de desarrollo en los metadatos.
¿No sería posible instalar poetry junto con pip , agregar alguna bandera en .readthedocs.yml como python.poetry_install=true y luego usar poetry install en la raíz del proyecto después de git checkout? Esto instalará el proyecto en modo editable con todas las dependencias de desarrollo.

Estoy intentando esto de nuevo para aria2p .

Aquí está mi configuración de RTD:

build:
    image: latest

python:
    version: 3.6
    pip_install: true

requirements_file: docs/requirements.txt

Anteriormente, tenía mi propio paquete aria2p en este archivo de requisitos para que funcionara:

sphinx==1.8.3
sphinx-rtd-theme==0.4.2
sphinxcontrib-spelling==4.2.0
toml==0.10.0
recommonmark==0.4.0
aria2p>=0.2.0

Significa que los documentos se crearon utilizando la última versión disponible, no el código obtenido localmente.

Hoy lo cambié a . , para usar el código local:

sphinx==1.8.3
sphinx-rtd-theme==0.4.2
sphinxcontrib-spelling==4.2.0
toml==0.10.0
recommonmark==0.4.0
.

Parece funcionar perfectamente en un contenedor Docker, pero aparece un error en RTD.

Historial de sesiones de Docker (raíz del proyecto montada en /code ):

docker run -v $(pwd):/code --rm -it python:3.6 bash

cd /code/
apt-get update
apt-get install python-enchant
pip install -U pip
pip install virtualenv
python -m virtualenv --no-site-packages --no-download VENV
/code/VENV/bin/python -m pip install --exists-action=w --cache-dir /root/.cache/pip -r docs/requirements.txt 
sphinx-build -E -b html docs build/docs

Error en RTD:

$ /home/docs/checkouts/readthedocs.org/user_builds/aria2p/envs/latest/bin/python -m pip install --exists-action=w --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/aria2p/.cache/pip -r docs/requirements.txt
Processing /home/docs/checkouts/readthedocs.org/user_builds/aria2p/checkouts/latest
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/home/docs/checkouts/readthedocs.org/user_builds/aria2p/envs/latest/lib/python3.6/tokenize.py", line 452, in open
        buffer = _builtin_open(filename, 'rb')
    FileNotFoundError: [Errno 2] No such file or directory: '/tmp/pip-req-build-2d9t32el/setup.py'

    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-req-build-2d9t32el/

Parece que pip todavía está buscando setup.py . ¿Podría ser esto un problema de caché?

EDITAR: de hecho, fue un problema de caché. Puede borrar el caché antes de reconstruir, consulte esta página https://docs.readthedocs.io/en/stable/guides/wipe-environment.html (gracias @stsewd)

Una cosa que podría ayudar a depurar este tipo de problemas sería la capacidad de ver la configuración utilizada para la compilación actual: readthedocs.yml si corresponde, y la configuración de Admin: Configuración y Admin: Configuración

Para resumir, estas son las cosas que probé:

• use un archivo requirements.txt para los documentos, agregue su paquete en él: my-package>=0.1.0 . No usará el último código, sino la última versión (que es suficiente la mayoría de las veces)
• use un archivo requirements.txt para los documentos, agregue . en él. Su paquete se instalará con pip install . , usando poesía, y su última versión de los documentos estará sincronizada con su rama maestra.
• use un archivo requirements.txt para los documentos, con solo las dependencias para los documentos. Agregue pip_install: true a la sección python de su archivo de configuración readthedocs.yml . Las dependencias se instalarán normalmente, luego se ejecutará el comando adicional pip install . . Es como la solución anterior, pero en dos pasos.

Por supuesto, cuando RTD y poesía estén más integrados, la necesidad de un requirements.txt podría desaparecer.

Mi última pregunta y esperaré comentarios antes de continuar mi inundación: ¿hay alguna manera de invalidar la caché de compilación?

Mi última pregunta y esperaré comentarios antes de continuar mi inundación: ¿hay alguna manera de invalidar la caché de compilación?

Sí, puede limpiar el entorno antes de activar una nueva compilación https://docs.readthedocs.io/en/stable/guides/wipe-environment.html

¡Sí! Eso hizo el truco, gracias: corazón: editaré mis comentarios arriba

@ rtfd / core discutió esto un poco hoy, y en su mayoría solo he resumido este problema ahora, pero parece que pip eventualmente admitirá la instalación con poesía. Si es así, creo que nuestra postura en este momento es que no implementaremos esto en RTD directamente, sino que esperaremos a que pip admita la instalación a través de la poesía.

Si hay alguien más íntimamente familiarizado con los planes de pip aquí, creo que aún nos gustaría recibir su opinión aquí. Nuestra preocupación se está extendiendo a nosotros mismos implementando herramientas de Python más específicas, pero también nos gustaría apoyar las herramientas comunes a la comunidad de Python.

Voy a cerrar este problema por ahora, pero estoy bien manteniendo esta conversación aquí si necesitamos reevaluar este problema.

@agjohnson
pip ya admite instalaciones de PEP-517 no editables y es por eso que es posible utilizar la siguiente solución alternativa:

build:
  image: latest

python:
  version: 3.6
  pip_install: true
  extra_requirements:
    - docs

Sin embargo, hay un inconveniente: las dependencias de RTD como sphinx y otros complementos deben aparecer como extras en pyproject.toml , que a su vez agregarán estos metadatos al paquete publicado en PyPi. En su lugar, preferiría mantener estas dependencias en la sección dev de pyproject.toml junto con otras herramientas de desarrollo como pytest , flake8 , etc.
Para habilitar este flujo de trabajo, RTD necesitaría instalar poetry y llamar a poetry install lugar de pip install .[docs] que podría controlarse con alguna bandera en .readthedocs.yml

El problema fundamental es que las "dependencias de desarrollo" de Poetry no se asignan directamente a un concepto que pip entiende. pip install instala el paquete en sí (+ cualquier extra especificado), lo que significa que solo las cosas enumeradas como dependencias del paquete entran en el entorno virtual. Actualmente, las dependencias de desarrollo no se consideran dependencias reales en ningún momento, excepto dentro de la propia poesía.

Sin embargo, los usuarios no están necesariamente indefensos: he publicado rtd-poetry que deberían descargar de forma transparente las dependencias de desarrollo utilizadas junto con un .readthedocs.yml como:

---
build:
  image: latest

python:
  version: 3.6
  pip_install: true

Solo verifica si está en RTD y agrega dependencias de desarrollo a los metadatos de la rueda, si es así. Pude usarlo con éxito para mi compilación de documentos aquí , pero chrahunt / rtd-poetry # 2 debe resolverse antes de que sea realmente utilizable.

@dmfigol, ¿hay alguna suposición no declarada en su ejemplo? Probé el .readthedocs.yml que escribiste y no funcionó para mí :

build:
  image: latest
python:
  version: 3.6
  pip_install: true
  extra_requirements:
    - docs

Processing /home/docs/checkouts/readthedocs.org/user_builds/project-template-python/checkouts/latest
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/home/docs/checkouts/readthedocs.org/user_builds/project-template-python/envs/latest/lib/python3.6/tokenize.py", line 452, in open
        buffer = _builtin_open(filename, 'rb')
    FileNotFoundError: [Errno 2] No such file or directory: '/tmp/pip-req-build-74uo7l0b/setup.py'

    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-req-build-74uo7l0b/

Es posible que debas borrar tu caché de compilación: https://docs.readthedocs.io/en/stable/guides/wipe-environment.html

Limpiar el medio ambiente lo hizo. ¡Gracias por las instrucciones, @pawamoy!

Conseguí que lo siguiente funcione para config v2

# .readthedocs.yml

version: 2

sphinx:
  configuration: docs/conf.py

python:
  version: 3.6
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

# pyproject.toml

[tool.poetry.dependencies]
sphinx = {version = "^3", optional = true}

[tool.poetry.extras]
docs = ["sphinx"]

Me haré eco del sentimiento de @dmfigol de que esto no es ideal por las razones que afirmó.

Ninguna de las opciones me funcionó, así que las instalé mediante programación en el archivo conf.py.

# -- Import statements -------------------------------------------------------

import os
import subprocess

if os.environ.get('READTHEDOCS') == 'True':
  # Install m2r for example
  subprocess.check_output(["pip", "install", "m2r"])

Solo un +1 para el método @jtpavlock detallado anteriormente, también funcionó para mí.

Tenga en cuenta que debe tener dichos paquetes enumerados como optional = true en la lista principal tool.poetry.dependencies y luego nuevamente en la lista extras > docs .