预览与发布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 # 可选，用于 monorepo
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

仓库中库源代码的路径。对 monorepo 很有用。

output.path
stringRequired

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

lang
stringRequired

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

config.doxyfile
string

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