Readthedocs.org: Soutenir la poésie

Quel serait le flux de travail de la poésie dans read the docs ? Le support Pipfile sera bientôt disponible. Si cela est implémenté, il vivra comme une option dans le fichier de configuration.

localement, je lance poetry install pour créer un virtualenv et installer les dépendances, puis poetry run sphinx-build ... pour exécuter sphinx-build à l'intérieur de ce virtualenv.

bien que s'il y a un virtualenv déjà actif, la poésie installera les dépendances à la place, ce qui signifie que cela devrait fonctionner de la même manière que pour requirements.txt ou Pipfile?

Mon workflow est assez similaire :

1. poetry install , qui installe les dépendances dev et prod par défaut
2. cd docs , étape facultative
3. poetry run make html , pour construire le site Web statique

Exemple de projet réel qui utilise à la fois poetry et rtd : https://github.com/wemake-services/wemake-django-template

Donc, remplacer le pas pip install par poetry install est tout ce qu'il faut ici ou il y a plus d'astuces que je ne vois pas ?

@humitos oui, je pense que oui.

N'oubliez pas que nous devons également travailler différemment avec venv : nous devons préfixer toutes les commandes avec poetry run .

si vous avez le venv actif, vous pouvez exécuter poetry install et il s'installera dans l'environnement actuel de la même manière que pip install -r requirements.txt , vous pouvez alors utiliser le venv comme vous l'auriez fait normalement.

poetry run est juste un raccourci pour exécuter des choses dans le venv sans avoir à se rappeler où il se trouve ou à l'activer en premier.

dépendances dev et prod

Existe-t-il un cas d'utilisation où les utilisateurs souhaitent uniquement installer les dev/prod deps ? Y a-t-il d'autres configurations que les utilisateurs peuvent vouloir définir ?

poetry install installera à la fois les dépendances dev et régulières
poetry install --no-dev n'installera que les dépendances régulières et aucun élément de développement

ce dernier ressemble plus à setup.py install avec la mise en garde qu'il n'installera pas le module lui-même, je ne peux pas penser à une raison impérieuse de ne pas installer de dépendances de développement pour la génération de documents ...

vous pouvez également utiliser poetry install --extras "foo bar" pour installer des groupes de dépendances supplémentaires foo et bar

les documents complets sont à https://poetry.eustace.io/docs/cli/#install

Je pense que ce problème se résoudra une fois la prochaine version de pip publiée avec le support PEP-517 (j'en ai entendu parler en janvier 2019 ?). Il a été fusionné - https://github.com/pypa/pip/pull/5743
Ensuite, un projet n'a qu'à ajouter

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

au pyproject.toml , et le pip install normal devrait fonctionner.

sauf que le script de construction exécute python setup.py install --force par défaut au lieu d'un pip install . donc pep-517 n'entrera pas en jeu ?

@danielknell, nous prenons en charge l'installation du projet à l'aide de pip.

@uSpike J'ai lu le problème pip et pep, mais je n'étais pas encore capable de le comprendre très bien :/ cela remplacera-t-il aussi pipenv?

@stsewd pip pourra peut-être s'installer à partir d'un Pipfile à un moment donné dans le futur, mais AFAIK, ce n'est pas sur la feuille de route de si tôt.

@danielknell - oui, vérifiez ici : https://docs.readthedocs.io/en/latest/yaml-config.html#python -pip-install, vous pourrez peut-être également le faire via la configuration Web. Alors, supposons que nous attendons simplement sur https://github.com/pypa/pip/issues/6106. @stsewd : une fois le pip 0.19.0 sorti, combien de temps avant qu'il ne devienne une image readthedocs que nous pouvons utiliser ?

Nous installons la dernière version de pip avant chaque build #4938, elle devrait donc être disponible après sa publication :)

Je ne connais pas très bien les environnements virtuels Python, mais il peut y avoir un autre problème.

J'exécute de la poésie à partir d'un script conf.py , mais j'obtiens l'erreur suivante, que je ne vois pas comment elle pourrait être corrigée du côté utilisateur :

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

Depuis la sortie du nouveau pip@19 , voici un bref aperçu de ce qui se passe.
J'ai vérifié localement le fonctionnement de pip@19 avec deux configurations :

1. Application : https://github.com/wemake-services/wemake-django-template
2. Bibliothèque : https://github.com/wemake-services/wemake-python-styleguide

Application

Essayer : pip install .
Résultat:

``` "Aucun fichier/dossier trouvé pour le package {}".format(nom)
poésie.masonry.utils.module.ModuleOrPackageNotFound : aucun fichier/dossier trouvé pour le package wemake-django-template

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

Commande "/Users/sobolev/Documents/github/wemake-django-template/.venv/bin/python3 /Users/sobolev/Documents/github/wemake-django-template/.venv/lib/python3.6/site-packages /pip/_vendor/pep517/_in_process.py prepare_metadata_for_build_wheel /var/folders/qn/2gssw9hx48g81chw0398hlrr0000gn/T/tmpbzmmkx48" a échoué avec le code d'erreur 1 dans /private/var/folders/qn/248Thlgsw9hx000gn/T/tmpbzmmkx48"
```

Une bibliothèque

Essayer : pip install .
Résultat : Il installe tout comme il se doit.

ça marche dans rtfd ? Je continue d'essayer mais je n'ai pas encore trouvé le temps de mettre à jour mes projets avec la configuration à installer via pip.

@sobolevn Je ne m'attendrais pas à ce que https://github.com/wemake-services/wemake-django-template s'installe car il s'agit d'un projet de modèle (cookiecutter).

@uSpike poetry install fonctionne, donc je m'attendais pip install ce que

poetry install n'installera que les dépendances dev/prod, pas le module lui-même
pip install . va essayer d'installer le module lui-même, et avec lui les dépendances prod.

le fait qu'il n'installe pas de dépendances de développement est préoccupant et peut-être que le pep 517 n'est pas suffisant pour soutenir pleinement les projets de poésie ?

poetry install installe également le projet lui-même en mode modifiable. https://github.com/sdispater/poetry/releases/tag/0.12.0

J'ai également essayé de rechercher ce problème dev / no-dev , il semble qu'il n'y ait pas encore de solution connue.

cela signifie que poetry install est équivalent à pip install -e .

Quelqu'un peut-il essayer un projet en rtd? Nous avons installé le dernier pip, faites-nous savoir s'il y a autre chose à faire de notre côté pour soutenir la poésie.

@sobolevn ce projet (https://github.com/wemake-services/wemake-django-template) est un modèle, vous n'êtes pas censé le pip install . L'équivalent est d'avoir un requirements.txt , mais ils ont utilisé de la poésie à la place. Le projet réel se trouve à l'intérieur de https://github.com/wemake-services/wemake-django-template/tree/master/%7B%7Bcookiecutter.project_name%7D%7D mais vous devez exécuter cookiecutter pour le faire.

@danielknell aah j'ai oublié ça... il pourrait y avoir un moyen de passer des drapeaux à la poésie via pip?

@uSpike douteux, pip et le pep lui-même n'ont vraiment rien dans ce sens, ce qui est compréhensible car il

il ressemble à installer un projet avec des dépendances de développement, la seule option est d'exécuter poetry install à l'intérieur du virtualenv.

Quels paramètres dois-je utiliser pour déclencher une installation ?
Si je vérifie la construction en utilisant setup.py il se plaint. Si je décoche, je n'essaierai pas
installer quoi que ce soit.

El jui., 24 ène. 2019 à 9h27, Daniel Knell ( [email protected] )
description :

@uSpike https://github.com/uSpike douteux, pip et le pep lui-même
n'ont vraiment rien de ce genre, ce qui est compréhensible car
il sort du cadre de la construction et de l'installation à partir de la source...

il semble que l'installation d'un projet avec des dépendances de développement soit la seule option
est d'exécuter l'installation de poésie à l'intérieur du virtualenv.

-
Vous recevez ceci parce que vous êtes abonné à ce fil.
Répondez directement à cet e-mail, consultez-le sur GitHub
https://github.com/rtfd/readthedocs.org/issues/4912#issuecomment-457215488 ,
ou couper le fil
https://github.com/notifications/unsubscribe-auth/ADdcSmGZO6hcPwZkAol5cbWdimuVNRAhks5vGcLYgaJpZM4Ynph9
.

@danielknell Je pensais que PEP-517 incluait des indicateurs pour que pip transmette des éléments au backend : https://www.python.org/dev/peps/pep-0517/#config -settings

Ceux-ci pourraient ensuite être capturés par la poésie dans https://github.com/sdispater/poetry/blob/master/poetry/masonry/api.py et changer la façon dont la dist est construite, peut-être pour inclure des dépendances de développement ?

@lorinkoz

# .readthedocs.yml
python:
   pip_install: true

la seule voie à suivre que je vois pour le moment, à moins d'utiliser vanilla sphinx, est de définir tout ce dont sphinx a besoin en tant que dépendances facultatives, puis de les ajouter à un groupe d'extras, puis d'utiliser une configuration comme :

build:
    image: latest

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

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

@danielknell Je suis d'accord, jusqu'à ce que https://github.com/pypa/pip/issues/5771 soit terminé et que la poésie ajoute la prise en charge de l'analyse de ladite configuration pour inclure les dépendances de développement dans une version.

Bref commentaire : pip install -e n'est pas encore supporté sans setup.py .

J'obtiens le Directory '.' is not installable. File 'setup.py' not found. habituel qui me fait penser que -e est passé.

Oui, je comprends que je ne peux pas installer un projet avec pip install . sans que ce soit une bibliothèque. Mais, ma question demeure : comment est-ce possible d'installer mes deps à partir de pyproject.toml intérieur de rtd ?

En d'autres termes : comment est-il possible de remplacer pip install -r requirements.txt qui est actuellement exécuté par quelque chose comme poetry install ?

@sobolevn nous ne prenons pas en charge l'exécution de poetry install .

@stsewd Je vois des échecs, même si le projet est configuré pour s'installer via la poésie et s'installe correctement avec pip install .[docs] localement, il échoue toujours à cause de l'absence de setup.py lors de la construction malgré les deux rapports pip 19.0.1, y a-t-il un moyen d'utiliser un pip différent à cette étape ou quelque chose du genre ?

voir:

build : https://readthedocs.org/projects/twelvefactor/builds/8456552/
code : https://github.com/artisanofcode/python-twelvefactor

il est intéressant de noter que celui-ci a déjà été adopté, sans aucun changement qui devrait avoir une influence sur l'installation :
https://readthedocs.org/projects/twelvefactor/builds/8456164/

différence entre les deux : https://github.com/artisanofcode/python-twelvefactor/compare/18b3e2b59765695053945778852e7860dd3cd8c6...cb6e69c70bc58e2c315a63cae7c56ae64c7b60b1

https://github.com/orsinium/poetry-setup peut être utilisé pour générer un setup.py et un requirements.txt alors que c'est toujours un problème.

Quel est le statut de ceci? Mes documents ont commencé à générer correctement.

@lorinkoz pouvez-vous s'il vous plaît partager votre configuration?

Configuration par défaut dans readthedocs concernant l'installation. Mon projet n'a qu'un pyproject.toml . D'après les journaux, RTD n'installe pas mes dépendances de développement, mais dans mon cas, elles ne sont pas obligatoires pour créer les documents.

Je suis également un utilisateur de poetry et si je pouvais stocker toutes les dépendances dans pyproject.toml , je serais heureux.
Je ne suis pas sûr que ce soit un travail de poetry de changer la façon dont ils construisent la roue avec l'API PEP517 - je ne pense pas qu'ils devraient inclure des dépendances de développement dans les métadonnées.
Ne serait-il pas possible d'installer poetry avec le pip , d'ajouter un indicateur dans .readthedocs.yml comme python.poetry_install=true puis d'utiliser poetry install dans la racine du projet après git checkout ? Cela installera le projet en mode modifiable avec toutes les dépendances de développement.

J'essaie à nouveau pour aria2p .

Voici ma config RTD :

build:
    image: latest

python:
    version: 3.6
    pip_install: true

requirements_file: docs/requirements.txt

Auparavant, j'avais mon propre package aria2p dans ce fichier d'exigences pour le faire fonctionner :

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

Cela signifie que les documents ont été créés à l'aide de la dernière version disponible, et non du code récupéré localement.

Aujourd'hui, je l'ai changé en . , pour utiliser le code local :

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

Cela semble fonctionner parfaitement dans un conteneur Docker, mais j'obtiens une erreur sur RTD.

Historique de session Docker (racine du projet montée sur /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

Erreur sur 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/

Il semble que pip recherche toujours un setup.py . Serait-ce un problème de cache ?

EDIT : en effet c'était un problème de cache. Vous pouvez effacer le cache avant de reconstruire, regardez cette page https://docs.readthedocs.io/en/stable/guides/wipe-environment.html (merci @stsewd)

Une chose qui pourrait aider à déboguer ce genre de problèmes serait la possibilité de voir la configuration utilisée pour la version actuelle : le readthedocs.yml cas échéant, et les paramètres de Admin:Settings et Admin:Advanced Settings.

Pour résumer, voici les choses que j'ai essayées :

• utilisez un fichier requirements.txt pour la documentation, ajoutez-y votre package : my-package>=0.1.0 . Il n'utilisera pas le dernier code, mais la dernière version (ce qui suffit la plupart du temps)
• utilisez un fichier requirements.txt pour les documents, ajoutez-y . . Votre package sera installé avec pip install . , en utilisant la poésie, et votre dernière version de la documentation sera synchronisée avec votre branche master.
• utilisez un fichier requirements.txt pour les documents, avec uniquement les dépendances pour les documents. Ajoutez pip_install: true à la section python de votre fichier de configuration readthedocs.yml . Les dépendances seront installées normalement, puis la commande supplémentaire pip install . sera exécutée. C'est comme la solution précédente, mais en deux étapes.

Bien sûr, lorsque RTD et poésie sont plus intégrées ensemble, le besoin d'un requirements.txt pourrait disparaître.

Ma dernière question et j'attends les retours avant de continuer mon flood : y a-t-il un moyen d'invalider le cache de build ?

Ma dernière question et j'attends les retours avant de continuer mon flood : y a-t-il un moyen d'invalider le cache de build ?

Oui, vous pouvez effacer l'environnement avant de déclencher une nouvelle version https://docs.readthedocs.io/en/stable/guides/wipe-environment.html

Oui! Cela a fait l'affaire, merci :heart: J'éditerai mes commentaires ci-dessus

@rtfd/core en a discuté un peu aujourd'hui - et je n'ai pour la plupart que parcouru ce problème à l'instant - mais il semble que pip soutiendra éventuellement l'installation avec de la poésie ? Si c'est le cas, je pense que notre position pour le moment est que nous n'implémenterons pas cela directement dans RTD, et attendrons plutôt que pip prenne en charge l'installation via la poésie.

S'il y a quelqu'un de plus familier avec les plans de pip ici, je pense que nous aimerions toujours votre contribution ici. Notre souci est de nous disperser en implémentant des outils Python plus spécifiques, mais nous aimerions également prendre en charge les outils communs à la communauté Python.

Je vais clore ce problème pour le moment, mais je vais bien continuer cette conversation ici si nous devons réévaluer ce problème.

@agjohnson
pip prend déjà en charge les installations PEP-517 non modifiables et c'est pourquoi il est possible d'utiliser la solution de contournement suivante :

build:
  image: latest

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

Cependant, il y a un inconvénient : les dépendances RTD comme sphinx et d'autres plugins doivent être répertoriés en tant qu'extras dans pyproject.toml , ce qui à son tour ajoutera ces métadonnées au package publié sur PyPi. Au lieu de cela, je préférerais conserver ces dépendances dans la section dev de pyproject.toml avec d'autres outils de développement comme pytest , flake8 , etc.
Pour activer ce workflow, RTD aurait besoin d'installer poetry et d'appeler poetry install au lieu de pip install .[docs] qui pourrait être contrôlé avec un indicateur dans .readthedocs.yml

Le problème fondamental est que les "dépendances de développement" de la poésie ne correspondent pas directement à un concept que pip comprend. pip install installe le package lui-même (+ tous les extras spécifiés), ce qui signifie que seules les choses répertoriées comme dépendances du package le font dans l'environnement virtuel. À aucun moment actuellement, les dépendances de développement ne sont considérées comme des dépendances réelles, sauf au sein de la poésie elle-même.

Cependant, les utilisateurs ne sont pas nécessairement impuissants - j'ai publié rtd-poetry qui devrait télécharger de manière transparente les dépendances de développement utilisées en conjonction avec le .readthedocs.yml comme :

---
build:
  image: latest

python:
  version: 3.6
  pip_install: true

Il vérifie simplement si vous êtes sur RTD et ajoute des dépendances de développement aux métadonnées de la roue si c'est le cas. J'ai pu l'utiliser avec succès pour la compilation de ma documentation ici , mais chrahunt/rtd-poetry#2 doit être résolu avant qu'il ne soit réellement utilisable.

@dmfigol y a-t-il une hypothèse non .readthedocs.yml vous avez écrit, et cela n'a pas fonctionné pour moi :

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/

Vous devrez peut-être effacer votre cache de construction : https://docs.readthedocs.io/en/stable/guides/wipe-environment.html

L'essuyage de l'environnement l'a fait. Merci pour les instructions, @pawamoy !

J'ai obtenu ce qui suit pour fonctionner pour la configuration 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"]

Je ferai écho au sentiment de

Aucune des options n'a fonctionné pour moi, je les ai donc installées par programme dans le fichier conf.py.

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

import os
import subprocess

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

Juste un +1 pour la méthode @jtpavlock détaillée ci-dessus, cela a fonctionné pour moi aussi.

Notez que vous devez avoir ces packages répertoriés à la fois comme optional = true dans la liste principale tool.poetry.dependencies , puis à nouveau dans la liste extras > docs .