文档贡献¶

用户文档以任务为入口，中英文核心页面必须成对维护。

页面顺序¶

说明任务和输入。
给出 5-20 行最短可运行示例。
紧跟真实输出、返回形状或生成文件树。
说明常用变体和实际限制。
链接到格式矩阵或精确契约。

终端用户示例使用 molop，只有开发环境命令使用 uv run molop。快速上手不得依赖 tests/test_files/、源码根目录或测试环境变量。

事实来源¶

API 名称和默认值：当前 Python 源码与类型提示。
CLI：molop --help 和具体子命令 help。
格式能力：tests/format_feature_coverage/support_matrix.py。
核心示例：docs/assets/examples/ 与 tests/test_documentation_examples.py。

不要手写与能力矩阵重复的“支持/不支持”表。

版本元数据¶

文档站必须明确标识其对应的源码，不得让主线文档看起来像当前 PyPI 发布版。scripts/mkdocs_hooks.py 在构建时从 Hatch VCS 和完整 Git tag 历史生成以下信息，并由全站横幅展示：

源码版本；
Git ref 和 commit；
最近稳定发布 tag；
development 或 release 文档状态。

文档工作流的 checkout 必须使用 fetch-depth: 0，否则无法可靠解析最近发布 tag。不要在 Markdown、mkdocs.yml 或模板中手写版本号。

发布部署使用 mike：稳定 tag 发布为 /<版本>/ 并更新 latest，main 发布为 main 并更新 dev；根地址默认指向 latest。Pages artifact 还会安装根级 404.html，把旧的无版本深链接转到 latest。不要手动复制版本目录或修改 versions.json。

无 Git 元数据的源码归档可以使用 MOLOP_DOCS_SOURCE_VERSION、MOLOP_DOCS_RELEASE_VERSION、MOLOP_DOCS_COMMIT、MOLOP_DOCS_REF 和 MOLOP_DOCS_CHANNEL 显式注入构建信息；MOLOP_DOCS_CHANNEL 只接受 development 或 release。

输出渲染¶

Markdown 示例中的输出必须作为独立的可折叠内容呈现。文档站点使用 Material details：

Markdown

??? example "输出"
    ```text
    ...
    ```

命令、输入代码和解释文字放在折叠块外。打印值、返回文本、生成的文件树以及用于核对的其他产物都遵守这条规则。README 使用原生 HTML <details>，因为 GitHub 不渲染 Material admonition。

Notebook 的输出由另一条流程负责：只编辑代码单元和 Markdown 单元，然后由 CI 在构建 MkDocs 前使用 nbconvert --execute 执行 Notebook。mkdocs-jupyter 以 execute: false 读取保存的 Notebook 并渲染 HTML；不要手动修改 Notebook 的 outputs、执行计数或生成的 HTML。

需要在 Markdown 页面直接展示某个 Notebook 单元格的 HTML 输出时，使用单元格 id 声明：

Markdown

<div class="molop-notebook-output" markdown="0">
<div>

<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>DiskStorage.FilePath</th>
      <th>DiskStorage.FileFormat</th>
      <th>General.Charge</th>
      <th>General.Multiplicity</th>
      <th>General.CanonicalSMILES</th>
      <th>General.NumAtoms</th>
      <th>General.FrameID</th>
      <th>Calc Parameter.Software</th>
      <th>Calc Parameter.Version</th>
      <th>Calc Parameter.Method</th>
      <th>Calc Parameter.BasisSet</th>
      <th>Calc Parameter.Functional</th>
      <th>Calc Parameter.Keywords</th>
      <th>Environment.SolventModel</th>
      <th>Environment.Solvent</th>
      <th>Status.IsError</th>
      <th>Status.IsNormal</th>
      <th>Status.IsTS</th>
      <th>Status.IsOptimized</th>
      <th>Energy.electronic_energy.hartree</th>
      <th>Energy.reference_energy.hartree</th>
      <th>Energy.mp2_energy.hartree</th>
      <th>Energy.total_energy.hartree</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>/home/runner/work/MolOP/MolOP/docs/assets/exam...</td>
      <td>.out</td>
      <td>0</td>
      <td>1</td>
      <td>O</td>
      <td>3</td>
      <td>0</td>
      <td>ORCA</td>
      <td>6.0.1</td>
      <td>MP2</td>
      <td>sto-3g</td>
      <td></td>
      <td>MP2 sto-3g</td>
      <td>None</td>
      <td>None</td>
      <td>False</td>
      <td>True</td>
      <td>False</td>
      <td>False</td>
      <td>-74.999375</td>
      <td>-74.963574</td>
      <td>-74.999375</td>
      <td>-74.999375</td>
    </tr>
  </tbody>
</table>
</div>
</div>

scripts/mkdocs_hooks.py 会读取已执行 Notebook 的 text/html 输出并嵌入当前语言页面。目标单元格必须有稳定 id，且 CI 执行后必须产生 HTML；不要把 DataFrame HTML 复制到 Markdown。

新页面¶

同一改动中完成：

docs/zh/... 中文页面。
docs/en/... 英文语义本地化页面。
mkdocs.yml 导航。
可执行代码对应测试。

校验¶

Bash

uv run rumdl check README.md README.zh.md $(rg --files docs -g '*.md')
uv run pytest -q tests/test_documentation_examples.py --no-cov
NO_MKDOCS_2_WARNING=1 uv run mkdocs build --strict