Python ReadTheDocs面临的挑战

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

默认方法是让ReadTheDocs完全访问我们的代码repo，其中的文档只是一个子文件夹。这是一个非启动，不可能

因此，我的下一个想法是将Docs文件夹的副本复制到一个单独的repo中，并允许ReadTheDocs访问它。这里的问题是，文档是从我们的代码自动生成的，所以这种方法会留下大量不完整的文档

ReadTheDocs似乎无法托管构建的文档网站（例如index.html等），但也许我错了

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

我们需要版本控制（如1.0.1、1.0.2等），导出到PDF文件是理想的选择

真诚地

Robert W.

有关API文档，您可以使用，或。

ReadTheDocs指南 我在自己的许多项目中使用了ReadTheDocs，它确实是一个有用的平台。据我从您的问题中了解到的情况，您正在尝试从存储库（GitHub repo？）托管HTML文件。然而，ReadTheDocs并不是为托管HTML而设计的——它实际上是使用（一个用Python编写的文档构建系统）构建重构的文本或标记文件。以下是设置ReadTheDocs以承载文档的典型场景：

初始化文件

首先，使用

pip安装Sphinx

——阅读指南了解如何安装

接下来，进入计算机上的克隆存储库，在

docs

文件夹中运行

sphinx快速启动
（必须是空文件夹）

司令部应该问你一些问题。选择以下答案：

• 将源目录和生成目录分开？

  ：n

• 项目名称

  ：一个整洁的面向公众的项目名称

• 作者姓名

  ：制作API的开发人员姓名

• 项目发布版

  ：API的当前版本

其余部分可以保留为默认值（按enter键选择默认选项）

将创建的文件提交到GitHub repo

注册ReadTheDocs帐户并导入存储库。默认情况下，它将在您的回购协议的根目录或其

docs

文件夹中构建它看到的任何内容（它将自动确定哪个）。如果一切顺利，您应该能够打开文档页面并查看演示页面

编写和编辑文档 您现在应该能够编辑文件以创建文档。RTD的设计基于“主题”，并且大多数页面使用。主题回购通常会提供不错的安装文档

要编辑页面，您需要编辑

docs/index.rst

。RST代表重组文本，类似于减价。你可以在网上找到它的备忘单。以下是自动生成的文件的外观：

.. 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`

您可以从底部删除“索引和表”部分——我不完全确定它的用途

。。目录树：：

是一个通用菜单-您只需在

index.rst

中定义它，就可以在其他页面上删除它。要创建新的文档页面，请创建一个新的

*.rst

文件。您所称的内容将对应于它呈现到的

.html

文件。例如，

parameters.rst

将通过

http://mydocs.readthedocs.org/en/latest/parameters.html

。要将

parameters.rst

页面添加到菜单中，需要如下所示：

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

   parameters

基本上，您需要将

.rst

文件的名称（不带扩展名）添加到

。。在
index.rst
文件中的目录树

（其他地方都没有）

应用更改 要应用所做的更改并将其发布到ReadTheDocs页面，您只需将新的

.rst

文件提交到GitHub上的

主
分支，RTD将自动为您构建和发布

如果您还没有完全理解，RTD不接受.html文件。您不应该将任何.html文件提交到GitHub，而应该只提交.rst文件。.rst文件将由RTD生成并发布

版本
您可以使用Git标记来管理文档的版本。有关更多详细信息，请参阅（官方ReadTheDocs文档）

希望这是有用的
 如果您的项目在GitHub上，那么您可以使用您选择的支持PDF生成的静态站点生成器（SSG）来满足您的需求

以最简单的形式，创建一个GH操作来生成分支/发布的静态站点文件夹，然后将该文件夹推送到GH页面所指向的分支中的相应文件夹，例如GH页面。应将其中一个分支/发布推送到根目录。可能会有帮助。向静态网站添加指向匹配文件夹的版本下拉列表

例如：






与ReadTheDocs免费计划相比的优势：


没有广告
完全托管在GitHub上，无需第三方服务或授权
向他们支付咨询workPal的费用，感谢您的回复。请原谅我没有说得更清楚。我们的文档采用斯芬克斯要求的格式。但我不能只是复制到另一个回购文件，因为我们的代码中有指向docstring的链接。我们也不能让ReadTheDocs完全访问我们的代码。鉴于这些限制，您会建议我们怎么做？您不能为RTD提供对您的代码的完全访问权限是什么意思？这是私人Github回购协议吗？RTD是