我可以在readthedocs.org上使用MkDocs的外部主题吗？

Question

我从包含的ReadtheDocs主题切换到我的项目的bootswatch United主题.我做了pip install mkdocs-bootswatch这个主题,并改变了theme: readthedocs对theme: united我的mkdocs.yml文件.

但是,尽管该项目在阅读文档中成功构建,但文档仍保留标准的readthedocs主题.当我在本地(使用mkdocs serve)运行它时,它与United主题正确显示.

还有另一行代码我应该在某处调整吗？我应该添加一个需求文件？如何让外部主题正确地出现在ReadtheDocs ......或者甚至可以在readthedocs.org上使用外部主题？

注意:我确实问过MkDocs的人,他们说这是一个ReadTheDocs限制,所以如果有什么要做,似乎它将是一个与ReadTheDocs相关的解决方案.否则,我可能不得不切换到GitHub页面或类似的东西.

Answer 1

我查看了 ReadtheDocs源代码，看来它们实际上覆盖了您的设置配置并强制使用自己的模板。据我了解，他们这样做是因为他们将特定于 ReadtheDocs 的 JavaScript 和导航内容注入到您的页面中，并且通过使用已知主题，他们可以确保注入正确完成。也就是说，不应该有任何技术原因导致您不能使用与 readthedocs 主题相同的 HTML，但可能使用不同的 CSS 来改变页面的外观/样式。只是 ReadtheDocs 似乎没有明确支持这一点。

也就是说，我确实注意到模板覆盖只会发生if 'theme_dir' not in user_config and self.use_theme。这为您提供了两种可能的途径来避免覆盖。请注意，无法保证注入的东西能够正常工作，因此请小心行事。

1. theme_dir是一个 Mkdocs设置。您可以将主题文件复制到旁边的目录中，docs_dir然后将设置指向theme_dir它，而不是将 MkDocs 主题安装为单独的 Python 库。请务必进行设置，theme: null以便 MkDocs 仅使用theme_dir.

   也许作为一种不太激进的方法，您可以设置theme: readthedocs，然后使用theme_dir来仅提供您自己的 CSS 文件，这将覆盖/替换内置 readthedocs 主题提供的 CSS。这应该不会对 ReadtheDocs 注入产生敌意，并且会给你一个你喜欢的外观。然而，这可能需要更多的工作才能完成，因为您仅限于现有主题的 HTML，并且需要编写自己的 CSS（不使用已构建的主题）。

   就此而言，您可以设置theme为您想要的任何主题，然后指向theme_dir一个空目录。看起来 ReadtheDocs 只检查设置theme_dir，并不关心目录中实际存在的内容。

   注意：我还没有测试过这些建议，不能确定它们是否有效。YMMV。

   顺便说一句，目前严重缺乏关于这一切如何工作（theme和设置之间的交互）的 MkdDocs 文档。theme_dir然而，当下一版本的 MkDocs (0.16) 发布时，一些最近添加的内容将生效。

2. use_theme似乎特定于 readthedocs 并在内部进行硬编码。我的猜测是，这不会被用户覆盖。需要对代码进行更深入的研究，以确定它提供了哪些选项（如果有）。