Generation

库文档生成器 Beta

以 Markdown 格式查看

库文档生成器解析你的 Python 或 C++ 库源代码，为模块、类、函数、方法和参数生成 MDX 文档页面。生成的页面会添加到你的 Fern Docs 站点中，并具有层次化的导航结构。

交叉链接是自动的。当完全限定的标识符出现在代码块中时——例如，在类签名或类型注解中——生成器会将其链接到记录该符号的页面，这样读者可以直接跳转到定义。

配置

1

在 docs.yml 中定义你的库

在你的 docs.yml 文件中添加 libraries 条目。每个库需要一个 input 源（要解析的仓库）、一个 output.path（生成的 MDX 文件写入的位置）和一个 lang（python 或 cpp）。

docs.yml
1libraries:
2  plant-core:
3    input:
4      git: https://github.com/acme/plant-core-cpp # 仓库 URL
5      subpath: packages/plant-core # 可选，用于 monorepos
6    output:
7      path: ./static/plant-core-docs # 相对于 fern/ 目录
8    lang: cpp # python 或 cpp
9    config:
10      doxyfile: ./Doxyfile # 可选，仅限 C++

你可以在同一个文件中定义多个库。

2

添加到导航

在你的导航中使用 folder: 条目指向你设置为 output.path 的同一目录。Fern 会发现该文件夹中的每个 MDX 文件，并将其子文件夹结构镜像到侧边栏部分。

docs.yml
1navigation:
2  - section: 开始使用
3    contents:
4      - page: 概述
5        path: ./pages/overview.mdx
6  - section: Plant SDK 参考
7    contents:
8      - folder: ./static/plant-sdk-docs
3

生成库文档

运行 CLI 命令从你的库源代码生成 MDX 文件：

$fern docs md generate

该命令会克隆仓库、解析源代码，并将 MDX 文件写入输出目录。

如果你配置了多个库，fern docs md generate 会并行处理所有库。使用 --library plant-sdk 仅为特定库生成文档。

4

本地预览

运行本地开发服务器查看你的库文档以及站点的其余部分：

$fern docs dev

库文档会显示为一个导航部分，包含库中每个模块、类、函数和类型的页面。

5

发布

发布你的库文档：

$fern generate --docs

你可以在同一个 docs.yml 中定义和引用多个库：

docs.yml
1libraries:
2  plant-python-sdk:
3    input:
4      git: https://github.com/acme/plant-sdk-python
5    output:
6      path: ./static/python-docs
7    lang: python
8  plant-core:
9    input:
10      git: https://github.com/acme/plant-core-cpp
11    output:
12      path: ./static/cpp-docs
13    lang: cpp
14
15navigation:
16  - section: Python SDK 参考
17    contents:
18      - folder: ./static/python-docs
19  - section: C++ API 参考
20    contents:
21      - folder: ./static/cpp-docs

自定义生成的文档（可选）

你可以重新组织输出目录来重构侧边栏导航。移动、重命名或嵌套文件和子文件夹，Fern 会在下次 fern docs dev 或发布时获取新布局。

例如，将 ./static/plant-sdk-docs 拆分为 getting-started/ 和 reference/ 子文件夹会产生两个侧边栏部分：

docs.yml
1navigation:
2  - section: Plant SDK 参考
3    contents:
4      - folder: ./static/plant-sdk-docs/getting-started
5        title: 开始使用
6      - folder: ./static/plant-sdk-docs/reference
7        title: API 参考

你还可以通过直接修改 MDX 文件来编辑页面内容——生成的页面是标准 MDX，因此你可以添加文本、示例、标注或任何组件。重新运行 fern docs md generate 会覆盖 output.path 中的所有内容，因此请先提交你的自定义修改，如果你计划重新生成，请将手动编辑的页面保留在输出目录之外。

配置参考

input.git
stringRequired

包含库源代码的仓库的 GitHub URL。

input.subpath
string

仓库内库源代码的路径。对 monorepos 很有用。

output.path
stringRequired

生成的 MDX 文件写入的目录，相对于 fern/ 目录。

lang
stringRequired

库的语言。支持的值：python、cpp。

config.doxyfile
string

自定义 Doxyfile 的路径。仅限 C++。