Readthedocs.org: MkDocs-Builds: erlaubt die Verwendung von MkDocs-eigenen Designs

Derzeit ist das Theme hartcodiert: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py#L147

:+1:

Der Hauptgrund ist, dass die standardmäßigen mkdocs-Themes keine Blöcke definiert haben, was bedeutet, dass wir keine der Vorlagen überschreiben können. Dies erschwert es uns, einen Teil des Kontexts auf Seitenebene einzufügen, der es uns ermöglicht, RTD-Funktionen zusätzlich bereitzustellen. Es ist etwas, das wir in Upstream-Mkdocs bekommen müssen, bevor wir es wirklich auf RTD unterstützen können.

In der Zwischenzeit denke ich, dass es gut wäre, den FAQ hinzuzufügen, dass benutzerdefinierte Designs derzeit nicht unterstützt werden, wenn mkdocs (zB nach dieser Frage ). Es könnte auch gut sein, hier eine Notiz hinzuzufügen: https://docs.readthedocs.org/en/latest/theme.html . Die aktuelle Anmerkung oben ist etwas vage darüber, worauf sie sich bezieht.

Mir war nicht klar, dass benutzerdefinierte Designs nicht unterstützt werden, bis ich dieses Problem gefunden habe.

Einverstanden mit @cjerdonek : Ich war überrascht, als meine lokal erstellte mkdocs-Website das gewünschte Thema verwendete und die Version auf RTD dies nicht widerspiegelte. Kein _großes_ Problem, aber es wäre fantastisch, wenn sie implementiert werden könnten oder irgendwo eine Notiz gemacht würde. Vielen Dank !

Gleiches Problem bei mir. Immer noch nicht dokumentiert.

Hier eine Notiz hinzuzufügen ist wahrscheinlich am sinnvollsten: https://github.com/rtfd/readthedocs.org/blob/master/docs/getting_started.rst

AFAICT, dies ist der einzige Teil der Dokumentation, der MkDocs behandelt.

:+1:

Der Hauptgrund ist, dass die standardmäßigen mkdocs-Themes keine Blöcke definiert haben, was bedeutet, dass wir keine der Vorlagen überschreiben können. Dies erschwert es uns, einen Teil des Kontexts auf Seitenebene einzufügen, der es uns ermöglicht, RTD-Funktionen zusätzlich bereitzustellen. Es ist etwas, das wir in Upstream-Mkdocs bekommen müssen, bevor wir es wirklich auf RTD unterstützen können.

@ericholscher Welche Blöcke werden benötigt? Es wäre gut, wenn wir das irgendwo irgendwie definieren könnten. Ich würde mich dann freuen, sicherzustellen, dass MkDocs diesem entspricht.

Soweit ich das beurteilen kann, sind die einzigen erforderlichen Blöcke für die Suchintegration und die Versionswechsler-Sache.

Würde hier auf jeden Fall gerne Fortschritte sehen. Ich denke, die Dinge werden noch komplizierter, sobald die MkDocs-Themen nur noch als Teil von http://mkdocs.github.io/mkdocs-bootswatch/ verfügbar sind.

Nicht wirklich, das wird nichts komplizieren, denke ich.

das wird nichts komplizieren denke ich

Sie möchten dieses Problem nicht OT nehmen, aber müsste RTD nicht mkdocs-bootswatch auf ihrer Infrastruktur _zusätzlich_ zu MkDocs verfügbar machen?

Benutzer können mit RTD beliebige Python-Pakete angeben. Wenn dies nur von MkDocs unterstützte Themen erlaubt, wäre es die Mühe nicht wert :)

Entschuldigung, aber mir ist der Status dieses Problems etwas unklar. Ist auf der Seite von MkDocs noch Arbeit erforderlich (um die oben genannten Blöcke zu definieren), oder müssen wir "nur" den MkDocs-Builder von RTD dazu bringen, das in mkdocs.yml angegebene Thema zu überprüfen und es zu verwenden, wenn es vorhanden ist?

@tatablack Ich glaube, die Arbeit ist nur auf der RTD-Seite erforderlich. Es stimmt, dass MkDocs möglicherweise nicht gut integriert werden könnten, wenn sie nicht den Erwartungen von RTD entsprechen (aber ich denke, dies gilt auch für benutzerdefinierte Sphinx-Themes).

Müssen Sie den MkDocs-Builder von RTD dazu bringen, das in mkdocs.yml angegebene Thema zu überprüfen und es zu verwenden, wenn es vorhanden ist?

Es ist eigentlich einfacher als das. Im Moment überschreibt RTD alle Themen, die Benutzer angeben. Um andere Themen zu aktivieren, muss RTD diese Einstellung einfach nicht mehr überschreiben.

Danke, @d0ugal. Ich habe gerade eine PR eröffnet (mit einer zugegebenermaßen einfachen Lösung), mal sehen, wie es läuft.

Wie ist der Status von RTD, benutzerdefinierte Themen zu unterstützen? Würden die RTD-Funktionen wie das Doc-Flyout in benutzerdefinierten Designs implementiert werden?

Derzeit sind wir dagegen, benutzerdefinierte Designs für mkdocs-Projekte auf RTD zuzulassen. Die Benutzererfahrung wird ohne die RTD-Ergänzungen zur Dokumentation beeinträchtigt, und die Zulassung benutzerdefinierter Designs würde unsere Bemühungen um eine zusammenhängende Benutzererfahrung nur noch weiter verwässern.

Ich stimme zu, dass benutzerdefinierte Designs auf Sphinx zum gleichen Effekt führen, eine verschlechterte Benutzererfahrung. Mir wäre viel lieber eine gemeinsame Schnittstelle zur projektübergreifenden Dokumentation. Zumindest mit Sphinx haben wir die Möglichkeit, Teile des Templating-Prozesses zu kontrollieren, um eine Injektion in alle Themen zu ermöglichen.

@agjohnson , ich stimme dem Label zu, das Sie auf PR #2188 ( Needed: design decision ) gesetzt haben, also möchte ich für benutzerdefinierte Themen argumentieren.

1. Solange der (potenzielle) Verlust bestimmter Funktionen gut dokumentiert ist, sollte es an den Autoren der Dokumentation liegen, eine fundierte Entscheidung zu treffen, die Vorteile eines benutzerdefinierten Themas für ihr Publikum zu bewerten und sie mit den Nachteilen der Nichtbereitstellung bestimmter RTD . zu vergleichen Funktionen, mit denen ihre Leser möglicherweise aus anderen RTD-Dokumentationssätzen vertraut sind.
2. Wenn es möglich/einfacher ist, ein benutzerdefiniertes Thema auszuwählen, _könnten_ einige von ihnen populärer werden, und dies _könnte_ zu Verbesserungen der Themen selbst führen, entweder von den ursprünglichen Autoren oder von jedem in der Community, der sie verwendet. Ich weiß , das ist hypothetisch, aber sicher , wenn ich nicht ein Thema verwenden
3. Sphinx vs. MkDocs. Was ich aus diesem Thread verstehe, ist, dass der Grad der Integration zwischen RTD und MkDocs nicht der gleiche ist wie bei Sphinx (in der Lage zu sein, "Teile des Vorlagenprozesses zu kontrollieren", wie Sie erwähnt haben). Allerdings (und dies könnte für diesen Thread nicht zum Thema gehören, halte mich ruhig, wenn das der Fall ist) Ich konnte nicht genau herausfinden, welche Hooks fehlen. @d0ugal :

Ein etwas seltsames Thema - es ist ungefähr 2 Jahre her, aber ich vermute, es gibt kein wirkliches Verständnis dafür, was für ein FTE-Thema erforderlich ist. Was sollte im MkDocs-Thema enthalten sein, damit es dem benutzerdefinierten Sphinx-Thema entspricht?

Wenn Sie sich entscheiden, benutzerdefinierte Designs überhaupt herunterzufahren - OK. Aber obwohl es erlaubt ist, scheint es keinen Grund zu geben, MarkDown-Autoren im Vergleich zu Sphinx-Autoren auf diese Weise einzuschränken.

¿Wie ist der Status dieses Problems?
Ich meine, es wird nicht behoben oder können wir etwas machen, um mkdocs-Themen mit RTD kompatibel zu machen?

Wie ich in Nr. 2188 erwähnt habe, haben wir uns entschieden, dies aus den dort aufgeführten Gründen nicht zu unterstützen.