ReadTheDocs指南

Question

我的任务是托管我们的Python API文档供我们的客户访问。 ReadTheDocs.com是由同事推荐的。但是，我遇到了一些挑战：

默认方法是让ReadTheDocs完全访问我们的代码仓库，其中文档只是一个子文件夹。这是一个非首发，不可能。
所以我的下一个想法是将Docs文件夹的副本复制到一个单独的仓库中，并允许ReadTheDocs访问它。这里的问题是文档是从我们的代码中自动生成的，因此这种方法会使大量文档不完整。
ReadTheDocs似乎无法托管构建的文档网站（即index.html等），但也许我对此有误？

我正在寻求遇到类似用例的其他人的帮助。您是否找到了一种方法让ReadTheDocs按您的要求工作，或者您是否转向另一种方法来托管您的文档？如果是后者，你使用了什么方法？

我们需要版本控制（即1.0.1,1.0.2等），导出到PDF文件将是理想的。

此致

Robert W。

Answer 1

ReadTheDocs指南

我已经将ReadTheDocs用于我自己的许多项目，它确实是一个非常有用的平台。至于我从你的问题中收集到的，你正试图从你的存储库托管HTML文件（GitHub repo？）。但是，ReadTheDocs不是用于托管HTML - 它实际上使用Sphinx（用Python编写的文档构建系统）构建ReStructuredText或Markdown文件。以下是设置ReadTheDocs来托管文档的典型方案：

初始化文件

首先，使用pip安装Sphinx - 阅读this以获取有关如何操作的指南。
接下来，进入计算机上的克隆存储库并在sphinx-quickstart文件夹中运行docs（必须是空文件夹）。
该命令应该问你一些问题。选择以下答案：
- Seperate source and build directories?： n
- Project name：项目面向公众的简洁名称
- Author name(s)：制作API的开发人员的姓名
- Project release：您当前的API版本
其余部分可以保持默认状态（按Enter键取默认选项）
将创建的文件提交到GitHub存储库。
注册ReadTheDocs帐户并导入您的存储库。默认情况下，它将构建它在repo的根目录中或在其docs文件夹中看到的任何内容（它将自动确定哪个）。如果一切顺利，您应该能够打开文档页面并查看演示页面。

编写和编辑文档

您现在应该可以编辑文件来创建文档。 RTD的设计基于“主题”，大多数页面使用https://github.com/rtfd/sphinx_rtd_theme。主题回购通常会提供合适的安装文档。

要修改页面，您需要修改docs/index.rst。 RST代表ReStructuredText，类似于Markdown。你可以在互联网上找到备忘单。以下是自动生成的文件：

.. Test documentation master file, created by
   sphinx-quickstart on Mon Mar 19 18:24:58 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

您可以从底部删除“索引和表格”部分 - 我不完全确定其用途。

.. toctree::是一个通用菜单 - 您只需要在index.rst中定义它，您就可以将其留在其他页面上。要创建新的文档页面，请创建一个新的*.rst文件。你所谓的它将与它所呈现的.html文件相对应。例如，parameters.rst可通过http://mydocs.readthedocs.org/en/latest/parameters.html访问。要将parameters.rst页面添加到菜单中，它需要如下所示：

.. toctree::
   :maxdepth: 2
   :captions: Contents:

   parameters

基本上，您需要将.rst文件的名称（不带扩展名）添加到.. toctree文件中的index.rst（以及其他任何地方）。

应用更改

要应用您所做的更改并将其发布到ReadTheDocs页面，您只需将新的.rst文件提交到GitHub上的master分支，RTD将自动构建和发布对你而言。

如果您还不太了解，RTD 不会使用.html文件。您不应该将任何 .html文件提交给GitHub，只需提交.rst文件。 .rst文件将由RTD构建并发布。

版本

您可以使用Git标记来管理文档的版本。有关更多详细信息，请参阅http://docs.readthedocs.io/en/latest/versions.html（官方ReadTheDocs文档）。

希望这很有用！

Answer 2

对于API文档，您可以使用swagger或apidoc。

Answer 3

如果您的项目在GitHub上，则可以使用Github Actions以及您选择的支持PDF生成的静态站点生成器（SSG）来满足您的要求。

以最简单的形式，创建GH动作以生成分支/发行版的静态站点文件夹，然后将该文件夹推送到GH页面所指向的分支中相应的文件夹，例如 gh-pages 。分支/发行版之一应推入根目录。 GitHub Pages Deploy Action可能会有所帮助。在指向匹配文件夹的静态网站中添加版本下拉列表。

示例：

ReadTheDocs免费计划的好处：

没有广告
完全托管在GitHub上，无需第三方服务或授权。

ReadTheDocs面临的挑战

3 个答案:

ReadTheDocs指南

初始化文件

编写和编辑文档

应用更改

版本