0

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

另外——我没有嫁给 RTD，这只是我在我的文档中使用的 MkDocs 主题，所以如果你们中的任何人有其他建议，开火吧！

4

2 回答 2

0

您可以查看ReadTheDocs的V2 文档

您将需要 2 个配置文件：

  1. mkdocs.yml
  2. .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 > Advanced Settings下）

于 2019-11-11T07:30:09.317 回答
0

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商业解决方案。

如果您已将Read the Docs 帐户连接到 GitHub、Bitbucket 或 GitLab，您将看到我们能够导入的存储库列表。要导入其中一个项目，只需单击要导入的存储库旁边的导入图标。这将打开一个已经填写了项目信息的表单。随意编辑这些属性中的任何一个，然后单击 下一步以构建您的文档。

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

在完成导入过程的几秒钟内，您的代码将自动从您的公共存储库中获取，并构建文档。查看我们的构建过程页面，了解有关阅读文档如何构建您的文档的更多信息，并解决出现的任何问题。

一些文档项目需要额外的配置来构建，例如指定特定版本的 Python 或安装额外的依赖项。readthedocs.yml您可以在文件中配置这些设置 。有关更多详细信息，请参阅我们的配置文件文档。

最后我检查了一下，默认情况下 RTD 没有使用最新版本的 MkDocs，因此您可能希望使用该readthedocs.yml文件来指定您编写文档所针对的 MkDocs 版本以及任何第三方插件、主题和/或您正在使用的 Markdown 扩展。

于 2019-06-10T20:04:53.830 回答