DDAC工作流的PyCharm项目前置准备清单

“工欲善其事，必先利其器”。本指南将引导您创建一个完美的、支持DDAC工作流的“项目模板”。

---

在PyCharm中创建新项目并设置虚拟环境

1. 打开PyCharm，选择 File > New Project...
2. 在弹出的窗口中，进行以下设置：
   • Location: 选择或创建一个空的项目目录。
   • New environment using: 强烈推荐选择 Virtualenv，以创建项目隔离的Python环境。
   • Base interpreter: 选择一个基础Python版本 (推荐 Python 3.9 或更高)。
3. 点击 Create 完成创建。

安装核心依赖

1. 打开PyCharm底部的 Terminal (终端) 工具窗口。确保命令提示符前有 (venv) 字样。
2. 在终端中，运行以下命令来安装所有必要的库：

   pip install sphinx sphinx-rtd-theme

3. 依赖说明: sphinx 是核心工具, sphinx-rtd-theme 是一个专业、美观的文档主题。
4. (推荐) 将初始依赖保存到 requirements.txt 文件中，便于管理：

   pip freeze > requirements.txt

初始化Sphinx项目

1. 仍在PyCharm的终端中，确保您位于项目根目录。
2. 运行Sphinx的快速启动命令：

   sphinx-quickstart

3. 根据引导进行配置，以下是关键回答：
   • Separate source and build directories (y/n) [n]: 输入 y (创建更整洁的结构)。
   • Project name / Author name(s): 按需填写。
   • Project language [en]: 输入 zh_CN (如果希望文档界面是中文)。
   • autodoc: automatically insert docstrings from modules (y/n) [n]: 输入 y (DDAC工作流的核心！)。

配置Sphinx (`conf.py`)

1. 在PyCharm项目树中，展开 docs/source 目录，双击打开 conf.py 文件。
2. 进行三处关键修改:
   1. 在文件顶部添加路径配置，让Sphinx找到你的项目代码：

      import os
      import sys
      # 告诉Sphinx你的项目代码在哪里 (从conf.py文件往上退两级到项目根目录)
      sys.path.insert(0, os.path.abspath('../..'))
      

   2. 找到 extensions = [...] 列表，确保它至少包含以下几项：

      extensions = ['sphinx.ext.autodoc',  # 核心：从docstrings自动生成文档'sphinx.ext.napoleon', # 支持Google/Numpy风格的docstring'sphinx.ext.viewcode', # 在文档中添加源码链接
      ]
      

   3. 找到 html_theme = 'alabaster'，将其修改为我们安装的专业主题：

      html_theme = 'sphinx_rtd_theme'
      

首次构建文档以验证设置

1. 在PyCharm的终端中，首先进入 docs 目录：

   cd docs

2. 然后执行构建命令：

   make html

3. 如果一切顺利，你不会看到任何红色错误信息。
4. 在项目树中，展开 docs/build/html 目录，找到 index.html 文件。
5. 右键点击 index.html，选择 Open in Browser。
6. 验证成功: 如果浏览器成功打开了一个漂亮的文档网页，那么恭喜你！你的DDAC就绪环境已全部准备完毕！

---

准备完成！

你的项目现在已经是一个“DDAC就绪”的标准化模板。下一步，就是打开你的另一份网页文档 "DDAC工作流手册与启动模板"，复制其中的“首次提示词模板”，正式开始你的项目开发！