Readthedocs.org: Ajouter un générateur de demande d'extraction de style travis-ci

Nous le faisons actuellement avec un constructeur Jenkins sur pyca/cryptographie, mais si nous pouvions le faire passer directement par RTD, ce serait merveilleux.

C'est sur notre radar, mais nous devons prendre des décisions de conception sur la façon de gérer les téléchargements HTML arbitraires sans autoriser les téléchargements HTML complètement arbitraires.

Fermer ceci comme un doublon d'un bogue dont je sais qu'il existe et que je trouverai plus tard :)

Ce n'est pas un ticket de téléchargement HTML arbitraire, c'est une demande de création automatique de branches à partir de PR de projets que nous connaissons. C'est certainement quelque chose que nous devrions faire.

La description du ticket ici semblait décrire la construction de documents sur Travis. Rouvrir ceci car nous décrivons une intégration de demande d'extraction Github/Bitbucket.

Certaines décisions de conception seraient nécessaires ici. À savoir, comment gérer les demandes d'extraction des branches sur les fourches compte tenu de notre modèle de données actuel. Nous pourrions facilement prendre en charge les branches poussées vers le référentiel que nous connaissons en élargissant le webhook pour gérer l'ouverture/la mise à jour des relations publiques.

Ce ticket ne concerne pas la création de documents sur travis ; il s'agit de créer des documents _dans le style de travis_. Autrement dit, à chaque poussée pour un PR, créez les documents et liez-les pour que les gens puissent les parcourir.

Si nous pouvions configurer des webhooks pour indiquer à readthedocs de créer des documents pour les demandes d'extraction qui touchent à la documentation, ce serait l'idéal.

Actuellement, lorsqu'une demande d'extraction arrive qui touche à la documentation, nous avons deux options distinctement désagréables :

1. Observez les modifications et fusionnez-les si elles semblent correctes, puis essayez de vous rappeler de revérifier rtfd lors de la création du maître fusionné.
2. Dites au demandeur de configurer rtfd pour sa succursale. Même les utilisateurs qui connaissent intimement sphinx/readthedocs rechignent souvent à cette demande, car il faudrait la refaire à chaque fois que la demande d'extraction utilise un nom de branche unique.

Je suis d'accord que cela a beaucoup de sens. Nous devons implémenter une sorte de version "temporaire" qui correspondrait au PR et cloner à partir du référentiel distant envoyant le PR. Ensuite, nous aurions besoin de supprimer la version lorsque la branche a été fusionnée, mais je suis d'accord que ce serait très utile.

ericholscher : Je pense que tout cela peut être fait sur la base des données des webhooks github, mais je n'ai aucune idée de l'emplacement du code d'implémentation. Je suppose que ce serait un nouveau point de terminaison pour le site rtfd ?

Bloqué sur #2465

Je ne sais pas comment l'API GitHub fonctionne dans ce cas, mais je pense que cette fonctionnalité #872 pourrait être utilisée pour cela

des nouvelles à ce sujet? Je construis des documents sphinx avec Travis sur plusieurs projets, mais il semble que même si la construction de documents avec travis peut réussir, cela peut ne pas réussir sur RTD, ce qui cause plus de problèmes.

Comme je trouve beaucoup plus facile de créer moi-même des documents, entièrement intégrés au pipeline CI, je commence à me demander quels sont les avantages réels de l'utilisation de RTD dans ce cas, car cela semble être un PITA.

Quelqu'un a-t-il réussi à trouver une solution de contournement qui empêcherait les gens de fusionner des PR qui casseraient la construction de la documentation RTD ?

@ssbarnea c'est ce que vous obtenez gratuitement de rtd :wink: https://docs.readthedocs.io/en/latest/features.html

Je ne sais pas comment cette fonctionnalité serait intégrée (rtd aurait beaucoup de docs _temporal_), vous pouvez avoir quelque chose comme ça pour vérifier vos builds

https://github.com/rtfd/readthedocs.org/blob/e73b266558af84745dd1cfc9e9dec7aa3e091dde/tox.ini#L21 -L24

Et peut-être en utilisant rstcheck (quelque chose comme ça https://github.com/rtfd/readthedocs.org/pull/3624)

J'aimerais l'utiliser en combinaison avec des branches protégées et des vérifications de statut, afin que les PR ne puissent être fusionnés que s'ils n'interrompent PAS le processus de construction sur RTD.
https://help.github.com/articles/about-protected-branches/
https://help.github.com/articles/about-required-status-checks/
https://developer.github.com/v3/repos/statuses/

si je pouvais au moins activer toutes les balises et branches en tant que versions rtd, je serais heureux.

pour le moment, il n'y a aucun moyen de tester un changement de doc sans publier une version bêta sur github (c'est-à-dire en utilisant une balise qui ressemble à une version)

@mouton-volant

pour le moment, il n'y a aucun moyen de tester un changement de doc sans publier une version bêta sur github (c'est-à-dire en utilisant une balise qui ressemble à une version)

Vous pouvez en fait créer une branche/balise qui n'a pas de _format de version_. Si vous créez une branche/balise nommée test , qui serait répertoriée dans la section des versions, vous pouvez l'activer et la construire. Si ce n'est pas ce que tu veux dire, désolé je n'ai pas compris.

C'est ce que je veux dire, mais je ne vois pas la balise apparaître dans la section des versions.

@flying-sheep rtd n'extrait pas automatiquement les balises via les webhooks (#3546), vous devez donc créer n'importe quelle version actuelle (comme la dernière par exemple) afin de rtd extraire les nouvelles balises/branches.

Si cela ne fonctionne pas, veuillez ouvrir un nouveau problème avec l'URL de votre projet rtd.

Merci!

Je viens d'avoir une réalisation à ce sujet, à savoir que GH nous permet d'accéder aux relations publiques d'un projet en tant que télécommande :

https://gist.github.com/piscisaureus/3342247

Vous pouvez ensuite vérifier un PR sur le repo de manière normale :

git reset --hard origin/pr/95

Cela nous permettrait de traiter les PR comme un autre type de version (Tag/Branch/Pull Request) et d'utiliser la modélisation RTD existante pour les prendre en charge. Nous pourrions alors avoir un synchroniseur personnalisé pour les relations publiques qui pousse le contenu dans un compartiment de type S3 au lieu de le conserver pour toujours, et peut-être que cette fonctionnalité est réalisée sans trop de travail.

Ouais, il y a un /merge et /head en dessous. Le premier est un commit de fusion généré avec la branche de base (vraisemblablement master ). Le second est le dernier commit sur le PR.

Peut également obtenir les deux en utilisant git fetch et éventuellement y attacher des branches localement. Nous l'utilisons beaucoup dans conda-forge. Heureux de répondre aux questions.

@ericholscher ce que vous dites ressemble à un plan. Est-ce toujours bloqué étant donné cela, ou est-il passé à la phase de besoin d'aide/de travail ? :+1:

Je pense que cela devrait être débloqué.

Il y a encore quelques décisions de conception, mais je pense qu'au moins pour GitHub, nous avons une voie à suivre.

Madame, Monsieur,

J'ai créé une application GitHub Probot qui permet de construire RTD et de partager son URL de document dans PR. Cela peut couvrir une partie de vos besoins, veuillez vérifier.

Fait intéressant, travis le fait également en utilisant les alias git : https://travis-ci.org/rtfd/readthedocs.org/jobs/482572527#L418

Cette fonctionnalité est acceptée et nous prévoyons de le faire. Notre plan est de le faire une fois que tous les artefacts de construction sont stockés dans le stockage blob (voir https://github.com/rtfd/readthedocs.org/pull/5549 pour commencer), car ce changement augmentera considérablement nos besoins de stockage car RTD stockerait indéfiniment la sortie de construction pour chaque construction de documents PR. Cela deviendra une priorité plus élevée dans la seconde moitié de 2019.

C'est merveilleux à entendre ! Si jamais vous voulez un bêta-testeur, n'hésitez pas à crier !

Nous avons cette fonctionnalité en version bêta https://blog.readthedocs.com/building-docs-for-pull-requests/

Je vais appeler celui-ci fermé, car il est maintenant dans la base de code. On va le déployer petit à petit, mais c'est fait 👍

Quelles sont les étapes de configuration pour un dépôt actuellement ?

@jakirkham tu veux dire en local ou sur le site ? Sur le site, vous devez demander un accès bêta https://blog.readthedocs.com/building-docs-for-pull-requests/

Pour une installation locale, vous devez activer ce drapeau pour vos projets EXTERNAL_VERSION_BUILD

https://docs.readthedocs.io/en/stable/guides/feature-flags.html

Vous pouvez le faire depuis l'administrateur de Features

Merci pour la réponse détaillée. Signifiait le site. Je ne savais pas si les choses avaient changé au cours des derniers mois.

Depuis que je trouve ce problème plus rapidement que les docs: https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html