Readthedocs.org: Fügen Sie den Pull-Request-Builder im Travis-ci-Stil hinzu

Wir machen das gerade mit einem Jenkins-Builder für Pyca/Kryptografie, aber wenn wir es direkt durch RTD bekommen könnten, wäre das wunderbar.

Dies ist auf unserem Radar, aber wir müssen einige Designentscheidungen treffen, wie wir mit willkürlichen HTML-Uploads umgehen, ohne völlig willkürliche HTML-Uploads zuzulassen.

Ich schließe dies als Duplikat eines Fehlers, von dem ich weiß, dass er existiert und den ich später finden werde :)

Dies ist kein willkürliches HTML-Upload-Ticket, sondern eine Aufforderung zum automatischen Erstellen von Branches aus PRs von Projekten, die wir kennen. Es ist definitiv etwas, was wir tun sollten.

Die Ticketbeschreibung hier schien Gebäudedokumente auf Travis zu beschreiben. Öffnen Sie dies erneut, da wir eine Github/Bitbucket-Pull-Request-Integration beschreiben.

Es gibt einige Designentscheidungen, die hier erforderlich wären. Nämlich, wie Pull-Requests von Branches auf Forks angesichts unseres aktuellen Datenmodells behandelt werden. Wir könnten leicht Zweige unterstützen, die in das uns bekannte Repo gepusht werden, indem wir den Webhook erweitern, um PR-Öffnungen/-Aktualisierungen zu handhaben.

In diesem Ticket geht es nicht darum, Dokumente auf Travis zu erstellen; Es geht darum, Dokumente _im Stil von Travis_ zu erstellen. Das heißt, erstellen Sie bei jedem Push für eine PR die Dokumente und verlinken Sie sie, damit die Leute sie durchsuchen können.

Wenn wir Webhooks einrichten könnten, um readthedocs anzuweisen, Dokumente für Pull-Requests zu erstellen, die die Dokumentation berühren, wäre das ideal.

Wenn derzeit eine Pull-Anforderung eingeht, die die Dokumentation berührt, haben wir zwei ausgesprochen unangenehme Optionen:

1. Beobachten Sie die Änderungen und führen Sie sie zusammen, wenn sie richtig _aussehen_, und versuchen Sie dann, daran zu denken, rtfd doppelt zu überprüfen, wenn es den zusammengeführten Master erstellt.
2. Sagen Sie dem Anforderer, dass er rtfd für seinen Zweig einrichten soll. Selbst Benutzer, die mit sphinx/readthedocs bestens vertraut sind, würden sich oft gegen diese Anfrage sträuben, da sie jedes Mal neu gemacht werden müsste, wenn die Pull-Anfrage einen eindeutigen Branch-Namen verwendet.

Ich stimme zu, dass dies sehr sinnvoll ist. Wir müssen eine Art "temporäre" Version implementieren, die dem PR zugeordnet wird, und aus dem entfernten Repository klonen, das den PR sendet. Dann müssten wir die Version löschen, wenn der Zweig zusammengeführt wurde, aber ich stimme zu, dass dies sehr nützlich wäre.

ericholscher: Ich denke, das kann alles basierend auf Daten von den Github-Webhooks gemacht werden, aber ich habe keine Ahnung, wo der Implementierungscode liegen würde. Ich nehme an, es wäre ein neuer Endpunkt für die rtfd-Site?

Blockiert auf #2465

Ich weiß nicht, wie die GitHub-API in diesem Fall funktioniert, aber ich denke, diese Funktion #872 könnte dafür verwendet werden

Gibt es Neuigkeiten zu diesem Thema? Ich erstelle Sphinx-Dokumente mit Travis für mehrere Projekte, aber es scheint, dass selbst wenn das Erstellen von Dokumenten mit Travis erfolgreich sein kann, es möglicherweise nicht auf RTD gelingt, was mehr Probleme verursacht.

Da ich es viel einfacher finde, selbst Dokumente zu erstellen, die vollständig in die CI-Pipeline integriert sind, frage ich mich langsam, was die wirklichen Vorteile der Verwendung von RTD in diesem Fall sind, da es sich anscheinend um eine PITA handelt.

Hat es jemand geschafft, eine Problemumgehung zu finden, die Leute daran hindert, PRs zusammenzuführen, die die Erstellung der FTE-Dokumentation unterbrechen würden?

@ssbarnea das bekommen Sie kostenlos von rtd :wink: https://docs.readthedocs.io/en/latest/features.html

Ich bin mir nicht sicher, wie diese Funktion integriert werden würde (rtd hätte viele _temporale_ Dokumente), Sie können so etwas haben, um Ihre Builds zu überprüfen

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

Und vielleicht mit rstcheck (so etwas wie https://github.com/rtfd/readthedocs.org/pull/3624)

Ich möchte dies in Kombination mit geschützten Zweigen und Statusprüfungen verwenden, sodass PRs nur zusammengeführt werden können, wenn sie den Erstellungsprozess auf RTD NICHT unterbrechen.
https://help.github.com/articles/about-protected-branches/
https://help.github.com/articles/about-required-status-checks/
https://developer.github.com/v3/repos/statuses/

wenn ich zumindest alle tags und branchs als rtd-versionen aktivieren könnte, wäre ich froh.

Im Moment gibt es keine Möglichkeit, eine Dokumentänderung zu testen, ohne eine Beta-Version auf Github zu veröffentlichen (dh mit einem Tag, das wie eine Version aussieht).

@fliegendes Schaf

Im Moment gibt es keine Möglichkeit, eine Dokumentänderung zu testen, ohne eine Beta-Version auf Github zu veröffentlichen (dh mit einem Tag, das wie eine Version aussieht).

Sie können tatsächlich einen Branch/Tag bauen, der kein _Versionsformat_ hat. Wenn Sie einen Branch/Tag mit dem Namen test erstellen, der im Abschnitt „Versionen“ aufgeführt wird, können Sie ihn aktivieren und erstellen. Falls das nicht gemeint ist, habe ich es leider nicht verstanden.

Das meine ich, aber ich sehe das Tag nicht im Versionsabschnitt.

@flying-sheep rtd zieht nicht automatisch Tags über Webhooks (#3546), daher müssen Sie eine aktuelle Version (wie zum Beispiel die neueste) erstellen, um rtd die neuen Tags/Zweige zu ziehen.

Wenn das nicht funktioniert, öffnen Sie bitte ein neues Problem mit Ihrer RTD-Projekt-URL.

Danke!

Ich hatte gerade eine Erkenntnis dafür, dass GH uns als Remote auf die PRs für ein Projekt zugreifen lässt:

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

Sie können dann ganz normal eine PR auf dem Repo auschecken:

git reset --hard origin/pr/95

Dies würde es uns ermöglichen, PRs als nur eine andere Art von Version (Tag/Branch/Pull Request) zu behandeln und die vorhandene RTD-Modellierung zu ihrer Unterstützung zu verwenden. Wir könnten dann einen benutzerdefinierten Syncer für PRs haben, der den Inhalt in einen S3-artigen Bucket verschiebt, anstatt ihn für immer dort zu behalten, und diese Funktion vielleicht ohne zu viel Arbeit erledigen.

Ja, da ist ein /merge und /head darunter. Der erste ist ein generierter Merge-Commit mit dem Basiszweig (vermutlich master ). Das zweite ist das neueste Commit auf der PR.

Kann auch beide mit git fetch erhalten und optional Branches lokal an sie anhängen. Wir verwenden dies häufig in Conda-Forge. Fragen gerne beantworten.

@ericholscher was du sagst klingt nach einem Plan. Ist dies angesichts dessen immer noch blockiert oder ist es in die Phase "Hilfe benötigt" / "Arbeit" übergegangen? :+1:

Ich glaube, das sollte entsperrt werden.

Es gibt noch einige Designentscheidungen, aber ich denke, zumindest für GitHub haben wir einen Weg nach vorne.

wen es angeht,

Ich habe eine GitHub-Probot-App erstellt, die es RTD ermöglicht, seine Dokument-URL in PR zu erstellen und zu teilen. Es kann einen Teil Ihrer Anforderungen abdecken, bitte überprüfen Sie dies.

Interessanterweise verwendet Travis auch die Git-Aliase: https://travis-ci.org/rtfd/readthedocs.org/jobs/482572527#L418

Diese Funktion wird akzeptiert und wir planen dies. Unser Plan ist, dies zu tun, nachdem alle Build-Artefakte im Blobspeicher gespeichert sind (siehe https://github.com/rtfd/readthedocs.org/pull/5549 für einen Anfang dazu), da diese Änderung unsere Speicheranforderungen erheblich erhöhen wird RTD würde die Build-Ausgabe für jeden PR-Document-Build auf unbestimmte Zeit speichern. Dies wird in der zweiten Hälfte des Jahres 2019 eine höhere Priorität erhalten.

Das ist wunderbar zu hören! Wenn Sie jemals einen Beta-Tester wollen, zögern Sie nicht zu brüllen!

Wir haben diese Funktion in der Beta- Version https://blog.readthedocs.com/building-docs-for-pull-requests/

Ich werde dies als geschlossen bezeichnen, da es jetzt in der Codebasis ist. Wir werden es langsam ausrollen, aber es ist geschafft 👍

Was sind die Schritte, um dies derzeit für ein Repo einzurichten?

@jakirkham meinst du lokal oder auf der Website? Auf der Website müssen Sie einen Beta-Zugang anfordern https://blog.readthedocs.com/building-docs-for-pull-requests/

Für eine lokale Installation müssen Sie dieses Flag für Ihre Projekte EXTERNAL_VERSION_BUILD aktivieren

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

Sie können dies über den Administrator von Features tun

Danke für die ausführliche Antwort. Gemeint war die Seite. Wusste nicht, ob sich die Dinge in den letzten Monaten geändert hatten.

Da finde ich dieses Problem schneller als die Dokumentation: https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html