Puis-je utiliser des thèmes externes avec MkDocs sur readthedocs.org?

Question

Je suis passé du thème ReadtheDocs inclus au thème bootswatch United pour mon projet. J'ai fait un pip install mkdocs-bootswatch pour ce thème et j'ai changé theme: readthedocs en theme: united dans mon fichier mkdocs.yml.

Toutefois, bien que le projet se connecte avec succès dans Read the Docs, la documentation conserve le thème readthedocs standard. Lorsque je l'exécute localement (en utilisant mkdocs serve), il apparaît correctement avec le thème United.

Y at-il une autre ligne de code que je devrais peaufiner quelque part? Un fichier de conditions que je devrais ajouter? Comment puis-je faire apparaître correctement le thème externe dans les ReadtheDocs ... ou bien, puis-je même utiliser des thèmes externes sur readthedocs.org?

Remarque: J'ai demandé aux gens de MkDocs et ils ont dit que c'était une limitation ReadTheDocs, donc s'il y a quelque chose à faire, il semble que ce sera une solution liée à ReadTheDocs. Sinon, je devrais peut-être passer aux pages GitHub ou quelque chose de similaire.

Answer 1

J'ai jeté un oeil à ReadtheDocs source code et il semble qu'ils écrasent réellement vos config de configurations et forcent leur propre modèle. Si je comprends bien, ils le font parce qu'ils injectent des éléments JavaScript et de navigation spécifiques à ReadtheDocs dans vos pages et en utilisant un thème connu, ils peuvent être sûrs que les injections sont faites correctement. Cela dit, il ne devrait y avoir aucune raison technique pour laquelle vous ne pouvez pas utiliser le même HTML que le thème readthedocs, mais peut-être des CSS différents pour modifier l'apparence/le style des pages. C'est juste que ReadtheDocs semble ne pas supporter explicitement cela. Cela dit, j'ai remarqué que le changement de modèle se produit seulement if 'theme_dir' not in user_config and self.use_theme. Cela vous donne deux chemins possibles pour éviter le remplacement. Sachez simplement qu'il n'y aura aucune garantie que les produits injectés fonctionneront correctement, alors marchez prudemment.

1. theme_dir est un Mkdocs setting. Plutôt que d'installer un thème MkDocs en tant que bibliothèque Python séparée, vous pouvez copier les fichiers de thème dans un répertoire à côté du docs_dir, puis pointer le paramètre theme_dir vers celui-ci. Assurez-vous simplement de définir theme: null afin que MkDocs utilise uniquement le theme_dir. Peut-être que dans une approche moins agressive, vous pouvez définir theme: readthedocs, puis utiliser theme_dir pour fournir uniquement vos propres fichiers CSS qui remplaceraient/remplaceraient le CSS fourni par le thème intégré readthedocs. Cela devrait être moins hostile aux injections de ReadtheDocs et vous donner un look que vous aimez. Cependant, cela peut nécessiter plus de travail pour obtenir le droit car vous êtes limité au code HTML du thème existant et devrez créer votre propre CSS (pas d'utilisation d'un thème déjà construit).

   D'ailleurs, vous pouvez définir theme sur le thème que vous voulez, puis pointez theme_dir vers un répertoire vide. Il semblerait que ReadtheDocs vérifie seulement que theme_dir est défini, et ne se soucie pas de ce qui existe réellement dans le répertoire.

   Note: Je n'ai testé aucune de ces suggestions et je ne peux pas être certain qu'elles fonctionneront. YMMV. En outre, la documentation MkdDocs sur la façon dont tout cela fonctionne (interaction entre les paramètres theme et theme_dir) fait cruellement défaut pour le moment. Cependant, certains récents additions deviendront actifs lorsque la prochaine version de MkDocs (0.16) sera publiée.

2. use_theme semble être spécifique aux readthedocs et hardcoded en interne. Ma conjecture est que ce ne sera pas remplaçable par un utilisateur. Une étude plus approfondie du code serait nécessaire pour déterminer quelles options, le cas échéant, cela fournit.