Question

我目前正在离开实习岗位，我正在为暑期实习生编写文件，该文件将在我毕业后接任。我已经使用MkDocs在Markdown中编写了所有文档，并且已经准备好部署它们。我的文档使用MkDocs附带的“阅读文档”主题，我希望将它们托管在RTD上。但是，我的文档的代码托管在属于我公司的GitHub组织的私人存储库中。由于我个人不是仓库，我遇到了使用RTD进行设置的问题。你们中有任何经验吗？我看过MkDocs 'Deploying your docs'，但是所有超链接都已过时，该指南主要涵盖了链接公共回购协议。

此外-我还没有嫁给RTD，这只是我在文档中使用的MkDocs主题，因此，如果您有其他建议，请辞职！

Answer 1

RTD似乎已将其文档移至https://docs.readthedocs.io/en/latest/。 RTD特定于MkDocs的文档位于https://docs.readthedocs.io/en/latest/intro/getting-started-with-mkdocs.html，但是，它没有提供有关如何部署基于MkDocs的网站的任何说明。

实际上，无论使用哪种受支持的静态站点生成器（Sphinx或MkDocs），部署到RTD的过程都是相同的，并记录在https://docs.readthedocs.io/en/latest/intro/import-guide.html：

要导入公共文档存储库，请访问您的Read the Docs dashboard，然后单击导入。对于私人存储库，请使用读取   文档commercial solution。

如果您有connected your Read the Docs account到GitHub，   Bitbucket或GitLab，您将看到我们的存储库列表   能够import。要导入这些项目之一，只需单击   您要导入的存储库旁边的导入图标。这将   弹出一个已经填满您项目的表格   信息。随意编辑任何这些属性，然后单击   下一步到build your documentation。

请注意，如果您没有（或不想拥有）您的GitHub帐户与RTD帐户关联，那么您将需要手动导入您的存储库，记录在here中。该文档继续：

在完成导入过程的几秒钟内，您的代码将   自动从您的公共存储库中提取，并且   文档将被建立。查看我们的Build Process页面以   详细了解“阅读文档”如何构建您的文档，以及   解决出现的任何问题。

某些文档项目需要其他配置才能构建   例如指定特定版本的Python或安装   其他依赖项。您可以在   readthedocs.yml个文件。有关更多信息，请参见我们的Configuration File文档   详细信息。

上次检查时，RTD默认情况下不使用最新版本的MkDocs，因此您可能想利用readthedocs.yml文件来指定编写文档所依据的MkDocs版本以及其他您正在使用的第三方插件，主题和/或Markdown扩展。

Answer 2

您可以查看ReadTheDocs的V2 Documentation

您将需要2个配置文件：

mkdocs.yml
.readthedocs.yml

两者都应位于项目/存储库的根目录

.readthedocs.yml 应该看起来像这样（如果您不使用任何其他插件）。

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation with MkDocs
#mkdocs:
#  configuration: mkdocs.yml
mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: false

# Optionally build your docs in additional formats such as PDF and ePub
formats: all

还请确保将您的 文档选项 更改为readthedocs仪表板上的MKdocs（在 Project > Admin 下） > 高级设置）

使用组织的专用存储库在“阅读文档”上部署MkDocs文档

2 个答案: