如何在 Forge Doc 中包含手动文档？

Question

背景

在 sphinx 中，可以在自动生成的文档中包含手动文档，例如使用

conf.py

文件。

但是，我无法找到如何在自动生成的 Solidity 文档中包含/添加手动文档。既没有在 forge 文档中关于文档生成，也没有在 forge 文档中关于如何配置 forge 文档。

尝试

我尝试添加手动目录

docs/manual/hello.md

内容：

# hello
some text.

并在

manual

的

src

行中添加

book.toml

目录，例如：

[book]
src = ["src", "manual"]  # Include both "src" and "manual" directories
title = ""

[output.html]
no-section-label = true
additional-js = ["solidity.min.js"]
additional-css = ["book.css"]
git-repository-url = "https://github.com/TruCol/Decentralised-Saas-Investment-Protocol"

[output.html.fold]
enable = true

但是，当我运行

forge doc --serve

时，这个

book.toml

被覆盖回：

[book]
src = "src"
title = ""

[output.html]
no-section-label = true
additional-js = ["solidity.min.js"]
additional-css = ["book.css"]
git-repository-url = "https://github.com/TruCol/Decentralised-Saas-Investment-Protocol"

[output.html.fold]
enable = true

docs/manual/hello.md

和内容将被保留。

问题

因此，我想问：“如何将手动文档嵌入/集成/包含到

forge doc --serve

自动生成的Solidity文档中？”

Answer 1

1. 停止自动覆盖 确保运行文档生成脚本时不会无意中重置或覆盖 book.toml。这可能涉及检查重新生成此文件的任何脚本或构建进程。

2. 验证您的配置 检查 forge-doc 或您的工具链版本是否有配置选项来指定其他文档源或目录。有时，文档工具提供允许额外自定义的命令行选项或环境变量

3. 定制集成 -如果 forge-doc 不支持直接通过 book.toml 集成手动文档，您可能需要在运行 forge doc --serve 命令后手动合并文档。这可以通过自定义脚本来完成，该脚本合并源代码和手册文档中的 mdbook 输出。 - 在运行 forge doc 之后但在使用 mdbookserve（或类似服务）提供内容之前，使用脚本将手动 Markdown 文件复制到输出目录。

 #!/bin/bash
forge doc --output path/to/output
cp -r docs/manual/* path/to/output/src/
mdbook build path/to/output
mdbook serve path/to/output

4. 手动调整 mdbook 配置 在运行 forge doc 之后和提供服务之前，直接修改输出目录中的 book.toml 。这也需要自动化，确保 src 配置包括您的 Solidity 源目录和手动文档目录