Readthedocs.org: Builds MkDocs : permet d'utiliser les propres thèmes de MkDocs

À l'heure actuelle, le thème est codé en dur : https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py#L147

:+1:

La raison principale est que les thèmes mkdocs par défaut n'ont pas de blocs définis, ce qui signifie que nous ne pouvons remplacer aucun des modèles. Il nous est donc difficile d'injecter une partie du contexte au niveau de la page qui nous permet de fournir des fonctionnalités RTD en plus. C'est quelque chose que nous devons entrer dans les mkdocs en amont avant de pouvoir vraiment le prendre en charge sur RTD.

En attendant, je pense qu'il serait bon d'ajouter à la FAQ que les thèmes personnalisés ne sont actuellement pas pris en charge lors de l'utilisation de mkdocs (par exemple après cette question ). Il pourrait également être bon d'ajouter une note ici : https://docs.readthedocs.org/en/latest/theme.html . La note actuelle en haut est un peu vague sur ce à quoi elle fait référence.

Il n'était pas clair pour moi que les thèmes personnalisés n'étaient pas pris en charge jusqu'à ce que je trouve ce problème.

D'accord avec @cjerdonek : j'ai été surpris lorsque mon site Web mkdocs construit localement a utilisé le thème que je voulais, et que la version sur RTD ne reflète pas cela. Ce n'est pas un problème _majeur_, mais ce serait fantastique s'ils pouvaient être mis en œuvre, ou qu'une note soit prise quelque part. Merci !

Même problème pour moi. Toujours pas documenté.

Ajouter une note ici est probablement le plus logique : https://github.com/rtfd/readthedocs.org/blob/master/docs/getting_started.rst

AFAICT, c'est la seule partie de la doc qui couvre MkDocs.

:+1:

La raison principale est que les thèmes mkdocs par défaut n'ont pas de blocs définis, ce qui signifie que nous ne pouvons remplacer aucun des modèles. Il nous est donc difficile d'injecter une partie du contexte au niveau de la page qui nous permet de fournir des fonctionnalités RTD en plus. C'est quelque chose que nous devons entrer dans les mkdocs en amont avant de pouvoir vraiment le prendre en charge sur RTD.

@ericholscher Quels blocs sont nécessaires ? Ce serait bien si nous pouvions définir cela quelque part, d'une manière ou d'une autre. Je serais alors heureux de m'assurer que MkDocs se conforme à cela.

D'après ce que je peux dire, les seuls blocs requis sont pour l'intégration de la recherche et le changement de version.

J'aimerais vraiment voir des progrès ici. Je suppose que les choses deviennent encore plus compliquées une fois que les thèmes MkDocs ne sont plus disponibles que dans le cadre de http://mkdocs.github.io/mkdocs-bootswatch/ .

Pas vraiment, ça ne va rien compliquer je pense.

ça ne va rien compliquer je pense pas

Vous ne voulez pas prendre ce problème OT, mais RTD ne devrait-il pas rendre mkdocs-bootswatch disponible sur son infrastructure _en plus_ de MkDocs ?

Les utilisateurs peuvent spécifier tous les packages Python arbitraires qu'ils souhaitent avec RTD. Si cela n'autorisait que les thèmes pris en charge par MkDocs, cela n'en vaudrait pas la peine :)

Mes excuses, mais je ne sais pas très bien où en est ce problème. Y a-t-il encore du travail à faire du côté de MkDocs (pour définir les blocs susmentionnés), ou nous devons « juste » faire en sorte que le constructeur MkDocs de RTD vérifie le thème spécifié dans mkdocs.yml et l'utilise s'il est là ?

@tatablack Je pense que le travail est juste nécessaire du côté de la RTD. Il est vrai que MkDocs pourrait ne pas bien s'intégrer s'ils ne correspondent pas aux attentes de RTD (mais je pense que c'est également vrai avec les thèmes Sphinx personnalisés).

besoin de faire en sorte que le constructeur MkDocs de RTD vérifie le thème spécifié dans mkdocs.yml et l'utilise s'il est là ?

C'est en fait plus simple que ça. Pour le moment, RTD écrase tout thème spécifié par les utilisateurs, pour activer d'autres thèmes, RTD a juste besoin d'arrêter d'écraser ce paramètre.

Merci @d0ugal. Je viens d'ouvrir un PR (avec une solution certes simpliste), voyons comment ça se passe.

Dans quel état RTD est-il capable de prendre en charge les thèmes personnalisés ? Les fonctionnalités RTD, telles que le menu volant doc, seraient-elles implémentées sur des thèmes personnalisés ?

Dans l'état actuel des choses, nous sommes opposés à l'autorisation de thèmes personnalisés sur les projets mkdocs sur RTD. L'expérience utilisateur est dégradée sans les ajouts de RTD à la documentation, et autoriser des thèmes personnalisés ne ferait que diluer davantage nos efforts pour une expérience utilisateur cohérente.

Je suis d'accord que les thèmes personnalisés sur Sphinx conduisent au même effet, une expérience utilisateur dégradée. Je préférerais de loin une interface commune à la documentation entre les projets. Au moins, avec Sphinx, nous avons la possibilité de contrôler certaines parties du processus de création de modèles pour permettre l'injection dans tous les thèmes.

@agjohnson , je suis d'accord avec l'étiquette que vous avez mise sur PR #2188 ( Needed: design decision ), donc j'aimerais plaider en faveur des thèmes personnalisés.

1. Tant que la perte (potentielle) de certaines fonctionnalités est bien documentée, il devrait appartenir aux auteurs de la documentation de prendre une décision éclairée, d'évaluer les avantages d'un thème personnalisé pour leur public et de les comparer aux inconvénients de ne pas fournir certains RTD. fonctionnalités que leurs lecteurs peuvent connaître à partir d'autres ensembles de documentation RTD.
2. S'il est possible/plus facile de choisir un thème personnalisé, certains d'entre eux _pourraient_ devenir plus populaires, et cela _pourrait_ conduire à des améliorations des thèmes eux-mêmes, soit par les auteurs originaux, soit par quiconque dans la communauté les utilise. Je me rends compte que c'est hypothétique, mais sûrement si je ne peux pas utiliser un thème, je ne me sentirai pas obligé de l'améliorer.
3. Sphinx contre MkDocs. Ce que je comprends de ce fil, c'est que le niveau d'intégration entre RTD et MkDocs n'est pas le même qu'avec Sphinx (pouvoir "contrôler des parties du processus de création de modèles", comme vous l'avez mentionné). Cependant (et cela pourrait être hors sujet pour ce fil, n'hésitez pas à me faire taire si c'est le cas) je n'ai pas pu trouver exactement quels crochets sont manquants. @d0ugal : êtes-vous au courant des améliorations qui pourraient être apportées du côté de MkDocs, et si oui, sont-elles possibles ?

Un problème un peu étrange - il s'agit d'environ 2 ans, mais je suppose qu'il n'y a pas vraiment de compréhension des exigences pour être un thème RTD. Que devrait contenir le thème MkDocs pour le rendre égal au thème Sphinx personnalisé ?

Si vous décidez d'arrêter les thèmes personnalisés, OK. Mais bien que cela soit autorisé, il semble qu'il n'y ait aucune raison de limiter les écrivains MarkDown de cette façon par rapport aux écrivains Sphinx.

Quel est le statut de ce problème ?
Je veux dire, ce n'est pas une solution ou nous pouvons faire quelque chose pour rendre les thèmes mkdocs compatibles avec RTD ?

Comme je l'ai mentionné dans #2188 -- nous avons décidé de ne pas soutenir cela, pour les raisons énumérées ici.