企业官网建设流程全解析

• 后端
• 文档

本篇技术指南围绕 Read the Docs 官方文档 docs/user/open-source-philosophy.rst 展开，系统梳理这个为 readthedocs.org 提供动力的开源项目在许可证选择、官方支持范围、明确不支持场景及其背后的决策逻辑，并结合仓库中的 LICENSE、setup.cfg、README.rst 与 docs/dev 下的开发文档，给出可验证的源码级依据。读完本文，你将理解 Read the Docs 开源模式的完整边界：什么场景可以获得官方支持、哪些使用方式会被明确拒绝、以及作为贡献者或自建者应如何与项目协作。

一、开源定位：以 MIT 许可承载的开放使命

Read the Docs 首先是开源软件。项目的官方文档明确写道：Read the Docs 是开源软件，其代码库以MIT 许可证发布，这为代码的使用提供了几乎没有任何限制的宽松条件。

这一选择在仓库中有多重可验证的证据：

• 仓库根目录的 LICENSE 文件完整声明了 MIT 许可条款，版权归属于Read the Docs, Inc. & contributors，并明确授予任何人使用、复制、修改、合并、发布、分发、再许可和销售该软件副本的权利；
• setup.cfg 的[metadata]段中license = MIT字段与License :: OSI Approved :: MIT License分类器，与包名readthedocs、版本号2026.09.22、描述 "Read the Docs builds and hosts documentation" 一并定义了该 Python 包的分发元数据；
• README.rst 末尾的 License 一节同样标注MIT © Read the Docs, Inc. & contributors。

不过，官方文档特别强调：作为一个项目，Read the Docs 有一些比代码本身更在意的东西。项目建立的初衷是支持开源社区中的文档事业：

• 代码对所有人开放贡献，使大家可以把想要的功能构建到 https://app.readthedocs.org 上；
• 团队相信开放共享代码本身是一种极具价值的学习工具，尤其是向外界示范如何协作并维护一个规模庞大的网站。

从仓库结构可以印证这一"庞大网站"的规模：readthedocs/目录下分布着projects/（含 169 个迁移文件）、builds/（80 个迁移文件）、search/、analytics/、organizations/、payments/、proxito/（文档托管代理层）等数十个 Django 应用，以及 dockerfiles/ 中面向 Web、Proxito、Celery 等多类进程的配置模板。这样的代码库完全开放，本身就是对大规模协作开发的一种示范。

二、官方支持范围：三件事，仅此三件

核心开发者（core developers）的时间是有限的。官方文档明确列出了 Read the Docs 提供官方支持的三类事项：

1. Python 代码库的本地开发：即在本仓库的 Python 代码上进行本地开发调试。对应的支撑材料是 docs/dev/install.rst 这份《Development installation》指南，它详细描述了基于 Docker 与 Docker Compose 的本地开发环境搭建步骤（Unix-like 系统、10 GB 以上磁盘空间、2 GB 内存、gVisor 沙箱等要求），并在开篇注明"该环境仅用于开发目的，不建议按此指南部署生产实例"。
2. 开源项目对托管服务的使用：即开源项目免费使用 https://app.readthedocs.org 这一托管服务。这与 docs/user/about/index.rst 中"为开源社区提供免费服务，通过伦理广告（ethical advertising）维持运营"的商业模式一致。
3. 代码库中 Bug 的修复：但仅限修复与在 https://app.readthedocs.org 上运行相关的缺陷。也就是说，修复的优先级锚定于官方托管环境本身。

这三条边界非常清晰：官方支持的对象是"本地开发"、"托管平台的使用"、"托管平台上的 Bug 修复"，而非任何自建部署形态。

三、明确不支持的范围：四类场景被排除

官方文档同样列出了项目不支持的使用场景，原因是这些场景不能推进其"在开源社区推广文档"的目标：

1. 不影响托管的 Sphinx 与 MkDocs 特定用法：如果某个 Sphinx/MkDocs 的使用技巧与 Read the Docs 托管服务无关，官方不会提供支持——因为那属于文档工具本身的问题范畴。
2. 在公司内部的自定义安装（custom installations）：官方不会花时间支持企业内网自建的 Read the Docs 实例。
3. 在其他平台上的安装：即安装到官方托管平台之外的任意平台。
4. 超出 Read the Docs Python 代码范围的一切安装问题：例如 Docker、操作系统、网络基础设施层面的部署问题，均不在官方支持范围内。

需要特别指出的是，"不支持"不等于"禁止"。文档在 Rationale 一节中明确说：Read the Docs完全认可并允许公司内部使用这套代码，只是不会投入时间进行支持。这是一种"许可但不护航"的姿态。

四、决策背后的 Rationale：时间与使命的取舍

官方文档给出了清晰的逻辑链条：

• Read the Docs 创立的初衷是改善开源社区中的文档生态；
• 团队完全认可并允许公司将代码用于内部安装，但不会花费时间支持它；
• 核心开发者的时间是有限的，团队希望把时间花在最初设定的使命上。

这一取舍在仓库中也有呼应：

• docs/user/security.rst 的《Supported versions》一节写道："只有最新版本的 Read the Docs 会收到安全更新，我们不支持对自定义安装的 Read the Docs 提供安全更新"，并将此直接链接到本文所依据的开源哲学文档——安全更新的支持边界与开源哲学的支持边界完全一致；
• docs/user/about/index.rst 同样声明"所有 Read the Docs 的源代码都是开源的，欢迎贡献你想要的功能或运行你自己的实例"，但紧接着注明"作为一项原则，我们通常只支持我们托管的版本"；
• 从 docs/dev/install.rst 的措辞（"不建议按此指南部署生产实例"）可以看出，项目提供的唯一官方部署路径就是其托管平台本身。

值得一提的是，官方文档也留下了合作通道：如果某家公司强烈希望在公司内部部署 Read the Docs，项目乐意链接到关于此主题的第三方资源，前提是有人愿意承担这件事——具体方式是开一个带有提案的 issue。这实际上为社区自建方案提供了一个开放接口，只是官方不亲自下场。

五、作为开源项目，如何与它协作

虽然自定义安装不在官方支持范围内，但"贡献"始终是被欢迎的。结合仓库内的协作资料，与 Read the Docs 协作的正确姿势如下：

• 本地开发：遵循 docs/dev/install.rst 搭建 Docker 开发环境（需要 Docker、Docker Compose、gVisor，磁盘 10 GB 以上），这是官方支持的三大事项之一；
• 提交代码：遵循 docs/dev/contribute.rst 的贡献指南，社区建议从标有Good First Issue标签的工单开始，进阶可关注Feature、Improvement、Accepted、Sprintable等标签的工单；所有参与者都需遵守 docs/dev/code-of-conduct.rst；
• 面向开源项目使用托管服务：按 README.rst 的 Quickstart，用 GitHub 账号登录、Add project、选择仓库，即可获得每次 push 自动重建文档的托管体验；
• 发现安全问题时：按 docs/user/security.rst 联系 security@readthedocs.org，在官方修复前不要公开披露。

六、总结：开源哲学的完整画像

Read the Docs 的开源哲学可以概括为四句话：

1. 代码完全开放：MIT 许可，几乎无使用限制，任何人可看、可学、可改、可用；
2. 支持边界明确：官方只支持"本地开发 Python 代码库、开源项目使用托管服务、托管环境相关的 Bug 修复"三件事；
3. 自建不被支持但被允许：公司内部安装、其他平台安装均被允许，但官方不提供支持、不提供安全更新，并把时间留给最初的使命——改善开源社区的文档生态；
4. 使命优先于规模：所有决策都围绕"支持开源社区的文档事业"展开，这是理解整个项目行为方式（包括商业模式、支持策略、安全策略）的钥匙。

对于计划深度使用 Read the Docs 的开发者而言，理解这层边界意味着：把精力放在"使用托管服务"和"贡献代码"两条官方支持的主线上；若确有自建需求，则应预期由自己或第三方社区资源来承担运维责任，而不是指望核心团队投入时间。

• 后端
• 文档