如何使用 Readthedocs / sphinx 在 monorepo 中记录项目？答案

【问题标题】：How do I document projects within monorepo using Readthedocs / sphinx?如何使用 Readthedocs / sphinx 在 monorepo 中记录项目？
【发布时间】：2022-06-30 05:23:02
【问题描述】：

我想利用readthedocs.org平台记录一组使用monorepo原理存储的相关软件。存储库结构如下：

/
+- ComponentA
|  |- docs
|  |- component-a-source
|
|- ComponentB
|  |- docs
|  |- component-a-source
|
|- ComponentC
|  |- docs
|  |- component-a-source
|
|- Makefile

我在 docs 目录中为每个子组件准备了文档，现在我遇到了麻烦：如何以惯用方式设置 readthedocs 来托管我的每个组件？

我找到的一个解决方案是在Web管理的高级设置部分中将存储库导入三次并手动将路径设置为conf.py；但是，我失去了使用.readthedocs.yaml 文件配置的可能性。

我想到的另一个解决方案是在根目录中创建单独的docs 目录，并以某种方式将三个文档合并到这个目录中。但它涉及组件文档和此“合并”文档之间的大量重复。我对狮身人面像的经验几乎为零。

在 readthedocs.org 中记录 monorepo 的惯用方式是什么？

【问题讨论】：

我了解到您想为每个组件设置一个单独的项目？有一些技巧可以做到这一点，只要我正确理解了您的问题，我可以提供更多详细信息。

标签： github python-sphinx monorepo read-the-docs

【解决方案1】：

Read the Docs 创建了一个 Sphinx 扩展来管理这个特定的用例。查看其文档https://sphinx-multiproject.readthedocs.io/

【讨论】：