文档系统

相关源文件

• docs/conf.py
• docs/index.rst
• docs/installation.rst
• docs/open_models.md
• docs/terms_link.rst

目的与范围

本文档介绍了gpt-engineer项目中使用的文档系统，解释了文档的结构、构建和维护方式。它涵盖了使用的工具和技术、文档文件的组织方式以及为文档贡献提供指南。

有关实现实际代码文档和文档字符串的信息，请参阅技术参考。

文档系统概述

gpt-engineer项目使用Sphinx作为其文档生成器，支持reStructuredText (.rst)和Markdown (.md)格式。这种混合方法在保持强大文档功能的同时提供了灵活性。

文档工具

来源：docs/conf.py61-69

文档结构

文档按以下结构组织成逻辑部分

来源：docs/index.rst1-41

文件格式与组织

文档系统支持两种主要文件格式：

1. reStructuredText (.rst) - 用于具有交叉引用、复杂表和指令等高级功能的结构化文档。
2. Markdown (.md) - 用于内容丰富的文档，写作方便很重要。

文件结构

文档文件组织在 docs/ 目录中，结构如下：

文件/目录	目的
conf.py	Sphinx 配置文件
index.rst	主目录
*.rst	reStructuredText 文档
*.md	Markdown 文档
_build/	生成的文档（不在仓库中）
_templates/	自定义 Sphinx 模板

来源：docs/conf.py1-205 docs/index.rst1-41

链接文件

文档使用特殊的“链接”文件来包含来自外部文件的内容

来源：docs/terms_link.rst1-3

构建文档

文档构建过程遵循典型的Sphinx流程

本地构建文档

要构建文档：

1. 安装所需的依赖项

2. 导航至 docs 目录

3. 构建 HTML 文档

4. 在 _build/html/index.html 查看文档

来源：docs/conf.py97-98 docs/conf.py127-128

配置详情

Sphinx 配置文件（conf.py）包含文档系统的重要设置

关键配置选项

设置	值	目的
extensions	扩展列表	启用 Sphinx 扩展
source_suffix	[".rst", ".md"]	支持的文件格式
html_theme	"sphinx_rtd_theme"	文档主题
autosummary_generate	True	自动生成 API 摘要
myst_enable_extensions	["colon_fence"]	MyST Markdown 扩展

来源：docs/conf.py61-69 docs/conf.py75 docs/conf.py128 docs/conf.py198 docs/conf.py200-202

API 文档配置

autodoc 扩展使用以下设置进行配置

这确保 API 文档包含类成员和继承信息。

来源：docs/conf.py89-94

贡献文档

在为 gpt-engineer 文档做贡献时，请遵循以下指南：

文档标准

1. 文件格式选择:

   • 为用户指南和内容丰富的文档使用 Markdown (.md)
   • 为结构化文档和高级功能使用 reStructuredText (.rst)

2. 文档风格:

   • 撰写清晰、简洁的技术信息
   • 包含实用示例
   • 使用正确的标题层级
   • 为复杂概念包含图表

3. 代码文档:

   • 使用文档字符串记录公共 API
   • 遵循 Google 或 NumPy 风格的文档字符串（由 napoleon 支持）
   • 包含类型提示

文档测试

在提交更改之前，务必在本地构建并测试文档，以确保

• 没有构建错误
• 链接功能正常
• 内容显示符合预期
• 代码示例工作正常

开放模型文档

项目包含有关使用 gpt-engineer 与开源 LLM 模型相关的特定文档，涵盖

1. 本地模型的设置说明
2. 基于性能的模型推荐
3. 配置示例
4. 测试过程

此部分展示了文档系统如何处理专业技术主题，结合了说明性文本、代码示例和命令行指令。

来源：docs/open_models.md1-149

特殊文档功能

多格式支持

文档系统使用 MyST 解析器支持 Sphinx 系统内的 Markdown

这使得作者可以根据自己的偏好和需求使用任何一种格式。

来源：docs/conf.py68 docs/conf.py75

自动 API 文档

文档系统从 Python 文档字符串中自动提取 API 文档

这使得 API 文档与代码保持同步。

来源：docs/conf.py62-64 docs/conf.py89-94

安装文档示例

文档包含一个 reStructuredText 格式的安装指南，演示了

1. 从 PyPI 安装
2. 从源代码安装
3. 常见问题故障排除

此示例展示了文档系统如何使用代码块和注释来处理技术过程。

来源：docs/installation.rst1-68