阅读文档教程

在本教程中，您将在Read the Docs上创建一个文档项目通过从GitHub存储库导入Sphinx项目，定制其配置，并探索平台的几个有用功能。

本教程面向对学习感兴趣的人如何使用Read the Docs来托管其文档项目。您将创建一个虚构的软件库类似于斯芬克斯官方教程.无需具备狮身人面像相关经验你可以在没有完成狮身人面像的情况下学习本教程。

你唯一需要的是web浏览器、Internet连接和GitHub帐户（你可以注册一个免费帐户如果你没有）。您将使用Read the Docs Community，这意味着该项目将公开。

入门

在GitHub上准备项目

首先，登录GitHub并导航到教程GitHub模板,在那里你会看到绿色使用此模板按钮。单击它可打开一个新页面，询问您一些详细信息：

保留默认的“所有者”，或将其更改为更好的教程项目。
引入适当的“存储库名称”，例如rtd教程.
确保项目是“公共”的，而不是“私有”的。

之后，单击绿色从模板创建存储库按钮，这将在您的个人帐户上生成一个新的存储库（或您选择的那一个）。这是您将在阅读文档时导入的存储库，它包含以下文件：

自述.rst: 存储库的基本描述，您将保持不变。
pyproject.toml软件: 使其可安装的Python项目元数据。用于从源代码自动生成文档。
卢马赫.py: 虚构Python库的源代码。
文档/: 保存所有Sphinx文档源的目录，包括Sphinx配置docs/source/conf.py文件和根文档docs/source/index.rst以reStructuredText编写。

注册阅读文档

要注册Read the Docs帐户，导航到注册页面并选择选项注册GitHub.在授权页面上，单击绿色授权阅读文档按钮。

注释

阅读文档需要提升权限才能执行某些操作确保工作流程尽可能顺畅，如安装网钩.如果你想了解更多，结账已连接帐户的权限.

之后，您将被重定向到阅读文档，您需要确认您的电子邮件和用户名。单击注册»按钮将创建您的帐户并将您重定向到您的仪表板.

现在，您应该有两个电子邮件通知：

一个来自GitHub，告诉您“第三方OAuth应用程序…最近被授权访问您的帐户”。你不需要这样做关于它的任何事情。
另一个来自Read the Docs，提示您“验证您的电子邮件地址”。单击链接以完成该过程。

完成后，将创建您的“阅读文档”帐户并准备导入您的第一个项目。

欢迎！

注释

我们的商业网站提供了一些额外的功能，比如支持私人项目。你可以了解更多我们的两个不同站点.

第一步

导入项目以阅读文档

要导入GitHub项目以阅读文档，首先单击导入项目仪表板上的按钮（或浏览至导入页面直接）。您应该会在右侧的“Filter repositories”列表下看到您的GitHub帐户。如果存储库列表为空，请单击🔄 按钮，之后，您的所有存储库都将显示在中心。

找到您的rtd教程项目（可能单击下一个››如果您有多页项目，请在底部），然后单击➕ 按钮。下一页将要求您填写有关阅读文档项目的一些详细信息：

姓名: 项目的名称。它必须在所有服务中都是唯一的，因此，如果您预先输入用户名，例如{用户名}-rtd-tutorial.
存储库URL: 包含源的URL。保留自动填充的值。
存储库类型: 使用的版本控制系统，保留为“Git”。
默认分支: 项目默认分支的名称，保留为主要的.
编辑高级项目选项: 不选中它，我们稍后将进行一些更改。

点击后下一步按钮，您将被重定向到项目主页.你刚刚在阅读文档上创建了第一个项目！🎉

检查第一个生成

阅读文档将尝试构建项目文档就在你创建它之后。要查看构建日志，单击您的文档正在构建上的链接项目主页,或者导航到“Builds”页面，然后打开上面的一个（最近的一个）。

如果在打开时构建尚未完成，您将在“安装”或“构建”指示器旁边看到一个微调器，这意味着它仍在进行中。

构建完成后，您将看到一个绿色的“构建完成”指示器，完成日期、经过的时间、，以及查看相应文档的链接。如果您现在单击查看文档，您将实时看到您的文档！

注释

广告是我们的主要收入来源之一。如果您想了解更多关于我们如何为运营提供资金的信息并探索无广告的选择，查看我们的可持续发展页面.

如果你没有看到广告，你可能正在使用广告拦截器。我们的EthicalAds网络尊重您的隐私，不针对您，并尽可能不引人注目，所以我们想请您不会阻止我们❤️

基本配置更改

现在您可以继续进行一些基本的配置调整。导航回项目页面然后单击⚙ 行政按钮，这将打开“设置”页面。

首先，在描述中添加以下文本：

Lumache（/lu'make/）是一个面向厨师和美食爱好者的Python库这创造了混合随机成分的食谱。

然后将项目主页设置为https://world.openfoodfacts.org/,然后写食物，蟒蛇在标签列表中。所有这些信息都将显示在您的项目主页上。

然后，配置电子邮件，以便在构建失败时收到通知。为此，请单击通知左侧的链接，键入您希望收到通知的电子邮件，然后单击添加按钮。之后，您的电子邮件将显示在“现有通知”下。

从拉请求触发生成

阅读文档可以让您GitHub拉请求的触发器构建并预览这些更改后文档的外观。

要启用该功能，请首先单击高级设置左侧的链接在⚙ 行政菜单中，选中“为此项目生成请求”复选框，然后单击保存按钮。

接下来，导航到GitHub存储库，找到文件docs/source/index.rst,然后单击✏️ 图标位于右上角，带有工具提示“编辑此文件”打开web编辑器（更多信息关于他们的文档).

在编辑器中，将以下句子添加到文件中：

docs/source/index.rst

Lumache的文档托管在Read the Docs上。

编写适当的提交消息，并选择“Create a新分支机构对于此提交并启动拉请求”选项，键入新分支的名称。完成后，单击绿色提出更改按钮，这将带您进入新的拉取请求页面，然后单击创建拉取请求按钮。

打开拉取请求后，将显示“读取文档”检查表示它正在为该拉请求构建文档。如果您单击细节链接，您将访问构建日志，否则，您将直接进入文档。当您满意时，可以合并拉请求！

自定义生成过程

的“设置”页面项目主页允许您改变一些全球的项目的配置值。此外，您可以进一步自定义构建过程使用.读取文档.yaml 配置文件.这有几个优点：

配置位于代码和文档旁边，由版本控制跟踪。
每个版本都可能不同（下一节将详细介绍版本控制）。
某些配置仅在使用配置文件时可用。

阅读没有此配置的文档通过代表你做一些决定.例如，要使用什么Python版本，如何安装需求，等等。

提示

应用于整个项目的设置在web仪表板中进行控制，而特定于版本或内部版本的设置在YAML文件中更好。

升级Python版本

例如，要显式使用Python 3.8构建项目，导航到GitHub存储库，单击添加文件按钮，并添加.读取文档.yaml将这些内容保存到项目的根目录中：

.读取文档.yaml

版本: 2

建造:
  操作系统: “ubuntu-20.04”
  工具:
    蟒蛇: "3.8"

每把钥匙的目的是：

版本: 强制，指定配置文件的版本2.
内置.os: 需要指定Python版本，说明基本映像的名称.
构建工具.python: 声明要使用的Python版本。

提交这些更改后，请返回项目主页，导航到“Builds”页面，并打开刚开始的新构建。您会注意到其中一行包含蟒蛇3.8:如果单击它，您将看到相应命令的完整输出，声明使用Python 3.8.6创建虚拟环境。

使警告更明显

如果您导航到HTML文档，您会注意到索引页看起来很正确但API部分为空。这是狮身人面像的常见问题，原因在构建日志中说明。在之前打开的构建页面上，单击查看原始右上角的链接，它以纯文本形式打开构建日志，您将看到几个警告：

警告：[autosummary]无法导入'lumache'：没有名为lumache的模块...警告：autodoc:无法从模块“lumache”导入函数“get_random_addings”；引发了以下异常：没有名为“lumache”的模块警告：autodoc:无法从模块“lumache”导入异常“InvalidKindError”；引发了以下异常：没有名为“lumache”的模块

为了更容易发现这些警告并允许您解决它们，您可以添加sphinx.fail_on_warning警告选项设置为“读取文档”配置文件。为此，导航到GitHub，找到.读取文档.yaml您之前创建的文件，单击✏️ 图标，并添加以下内容：

.读取文档.yaml

版本: 2

建造:
  操作系统: “ubuntu-20.04”
  工具:
    蟒蛇: "3.8"

狮身人面像:
  故障_警告: 真的

此时，如果您导航回“构建”页面，你会看到一个失败构建，这正是预期结果：Sphinx项目尚未正确配置，现在构建失败了，而不是呈现空的API页面。

原因sphinx.ext.自动摘要和狮身人面像ext.autodoc未能导入代码是因为未安装代码。幸运的是.读取文档.yaml还允许您指定要安装的要求。

要安装项目的库代码，返回编辑.读取文档.yaml并对其进行如下修改：

.读取文档.yaml

蟒蛇:
  #在构建文档之前安装我们的python包
  安装:
    - 方法: pip（点阵）
      路径: .

通过此更改，Read the Docs将安装Python代码在开始斯芬克斯建造之前，它将无缝完成。如果现在转到HTML文档的API页面，你会看到蜗牛壳总结！

启用PDF和EPUB生成

除了HTML之外，Sphinx还可以构建其他几种格式，例如PDF和EPUB。您可能希望为项目启用这些格式这样用户就可以脱机阅读文档。

为此，请将此额外内容添加到您的.读取文档.yaml:

.读取文档.yaml

狮身人面像:
  故障_警告: 真的

格式:
  - pdf格式
  - 电子书

更改后，可以下载PDF和EPUB都可以从项目主页,以及出菜单.

版本控制文档

阅读文档可以让您文档的几个版本,以同样的方式，您有多个版本的代码。默认情况下，它创建一个最新的版本指向版本控制系统的默认分支(主要的在本教程中），这就是为什么HTML文档的URL包含字符串/最新的/.

创建新版本

假设您想创建一个1代码的版本，具有相应的1文档的版本。为此，首先导航到GitHub存储库，单击分支选择器，类型1.0倍，然后单击“Create branch:1.0.x from'main'”（更多信息关于他们的文档).

接下来，转到您的项目主页，单击版本按钮，在“活动版本”下，您将看到两个条目：

这个最新的版本，指向主要的分支。
一个新的稳定的版本，指向原点/1.0.x分支。

创建分支后，阅读文档创建了一个新的特殊版本，名为稳定的指向它，并开始建造。建造完成后，这个稳定的版本将列在出菜单你的读者可以选择它。

注释

阅读文档遵循一些规则决定是否创建稳定的指向新分支或标记的版本。为了简化，它将检查名称是否与版本号相似喜欢1,2.0.3或4.x个.

现在您可能需要设置稳定的作为默认版本,而不是最新的,以便用户看到稳定的文档当他们访问根URL文档的（同时仍然可以在弹出菜单中更改版本）。

为此，请访问高级设置链接在⚙ 行政项目主页的菜单，选择稳定的在“默认版本*”下拉列表中，然后打保存在底部。完成！

修改版本

两者都有最新的和稳定的现在是积极的，这意味着它们对用户可见，并且可以为它们触发新的构建。除此之外，Read the Docs还创建了一个非活动的 1.0倍版本，它将始终指向1.0倍存储库的分支。

让我们激活1.0倍版本。为此，请转到您的项目主页,定位1.0倍在“激活版本”下，然后单击激活按钮。这将带您进入带有两个复选框的新页面，“活动”和“隐藏”。仅选中“活动”，然后单击保存.

在你这样做之后，1.0倍将显示在“活动版本”部分，并将为其触发一个新的构建。

注释

你可以阅读更多关于隐藏的版本在我们的文档中。

显示旧版本的警告

当项目成熟时，版本的数量可能会增加。有时你会想警告读者当他们浏览文档的旧版本或过时版本时。

为了演示如何做到这一点，让我们创建一个2代码版本：导航到GitHub存储库，单击分支选择器，类型2.0.x版，然后单击“Create branch:2.0.x from'main'”（从“主”创建分支：2.0.x）。这将触发两件事：

自2.0.x版是你最新的分店，稳定的将切换到跟踪它。
一个新的2.0.x版版本将在“阅读文档”项目中创建。
因为您已经有一个活动稳定的版本，2.0.x版将被激活。

从这一点来看，1.0倍版本不再是最新的。要向读者显示警告，请转到⚙ 行政项目主页的菜单，单击高级设置左侧的链接，启用“Show version warning”复选框，然后单击保存按钮。

如果您现在浏览1.0倍文档，您将在顶部看到警告鼓励您浏览最新版本。整洁！

从项目中获取见解

一旦您的项目启动并运行，您可能想了解读者如何使用您的文档，解决一些常见问题，如：

哪些页面是访问次数最多的页面？
最常用的搜索词是什么？
读者找到他们想要的了吗？

阅读文档为您提供了一些分析工具来找出答案。

浏览流量分析

这个如何使用流量分析视图显示了过去30天顶部查看的文档页面，再加上那段时间内每日视图的可视化。要在新创建的项目上生成一些人工视图，您可以先单击项目的不同页面，将立即计入当日统计。

要查看流量分析视图，请返回项目页面再一次，单击⚙ 行政按钮，然后单击交通分析第节。您将看到按访问次数降序排列的页面列表，以及与下面类似的图。

注释

上述交通分析视图为您提供了一个简单的概述读者如何浏览文档。它的优点是它没有存储访客的身份信息，因此，它尊重他们的隐私。然而，您可能希望通过以下方式获得更详细的数据启用谷歌分析.尽管我们采取了一些额外的措施尊重用户隐私当他们访问启用了Google Analytics的项目时，这可能会减少已统计的访问次数。

最后，您还可以下载此数据以进行更仔细的检查。为此，请滚动到页面底部然后单击下载所有数据按钮。这将提示您下载CSV公司文件你可以按你想要的方式处理。

浏览搜索分析

除了流量分析之外，阅读文档还提供了以下可能性检查你的读者使用什么搜索词在您的文档中。这可以帮助决定加强哪些方面，或者你的项目中哪些部分不太被理解或更难找到。

为了生成项目的一些人工搜索统计信息，转到HTML文档，找到左侧的Sphinx搜索框，类型成分，然后按输入键。您将被重定向到搜索结果页面，其中将显示两个条目。

接下来，返回⚙ 行政项目页面的部分，然后单击搜索分析第节。您将看到一个包含搜索次数最多的查询的表（包括成分你刚输入的），每个查询返回了多少结果，以及搜索了多少次。在查询表下面，您还将看到一个可视化过去30天内每天的搜索查询数。

与交通分析一样，您也可以下载CSV格式的整个数据集通过单击下载所有数据按钮。

从这里到哪里

本教程到此结束。您从分叉GitHub存储库开始并将其导入Read the Docs，构建HTML文档，然后完成了一系列自定义构建过程的步骤，调整项目配置，并添加新版本。

这里有一些资源可以继续学习文档并阅读文档：

您可以了解有关平台功能的更多信息通过检查我们的特征第页。
为了充分利用所支持的文档生成器，你可以阅读狮身人面像教程或MkDocs用户指南.
显示示例项目并在中读取源代码示例项目.
无论您是文档作者、项目管理员、开发人员还是设计师，您可以遵循我们涵盖特定任务的操作指南，在下可用操作指南A-Z.
对于私人项目支持和其他企业功能，你可以使用我们的商业服务（如果有疑问，请检查在我们的两个平台之间进行选择).
你想加入一个全球伙伴社区吗纪录片制作人?结账编写文档和其Slack工作区.
你想参与阅读文档吗？我们非常感谢！结账帮助阅读文档.

快乐记录！