企业官网建设流程全解析

Podman 文档体系解析：从 Markdown 源码到在线手册的完整构建指南

【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman

导读

本文以 Podman 仓库的 docs/README.md 为主线，系统梳理 Podman 文档的组织结构、构建流程与发布机制。你将掌握如何从docs/source/markdown/下的 Markdown 源文件生成标准 man 手册、Sphinx HTML 文档，以及面向 Windows/macOS 的远程客户端文档，同时理解 Swagger API 参考的自动化生成链路。读完本文，你可以独立完成 Podman 文档的本地构建、本地预览与格式校验，并理解每一类构建产物的来源与去向。

文档体系总览

Podman 的文档并非单一文件，而是一套分层体系：在线手册（Read The Docs 平台发布）、man 手册（本地构建）、远程客户端文档（Windows/macOS/FreeBSD 专用）与 API 参考（Swagger/Redoc）。它们共享同一份 Markdown 源头，通过不同的构建管线产出不同格式。

在源码仓库中，所有内容都围绕docs/目录组织：

文档源码的组织方式

Markdown 源文件

docs/source/markdown/目录下存放全部 man 页面的 Markdown 源，命名遵循podman-<command>.1.md的约定，例如 podman-run.1.md、podman-create.1.md、podman-quadlet.1.md。部分文件以.1.md.in结尾（如podman-create.1.md.in），它们不是最终源，而是需要经过预处理展开的模板。

以 podman.1.md 开头为例，可以看到每份 man 源以% podman 1标题行起始，随后依次是 NAME、SYNOPSIS、DESCRIPTION、GLOBAL OPTIONS 等章节，其中每个 OPTION 使用####四级标题（如#### **--events-backend**=*type*），并明确标注默认值与可用值范围。

.md.in模板与预处理机制

.md.in文件通过仓库根目录 Makefile 中的$(MANPAGES_MD_GENERATED)规则，由 hack/markdown-preprocess 工具转换为最终.md文件。该工具是一个 Python 预处理脚本，支持类模板语法，例如：

<< if variable >> ... << endif >> << if not variable >> ... << else >> ... << endif >>

这种机制让同一份模板可以针对不同平台（如是否支持 rootless、是否包含远程选项）产出差异化的 man 页面，避免多份源文件重复维护。从 hack/markdown-preprocess 的源码结构可以推断，它维护pod_or_container等上下文变量来区分命令作用对象。

links 目录：别名机制

links/ 目录存放的是.so格式的 man 别名文件，例如podman-container-run.1、podman-container-ls.1、podman-play-kube.1。这些是标准 man 系统的软链接指令文件，用于把历史/别名命令指向同一个真实 man 页面，同时与remote-docs.sh的发布逻辑深度耦合（下文详述）。

构建标准 man 手册：make docs

在源码根目录执行：

make docs

即可构建全部标准 man 手册，产物输出到docs/build/man/。Makefile 中的docs目标（见 Makefile 的 "Documentation targets" 段）在生成全部.1文件后，还会执行：

ln -sf $(CURDIR)/docs/source/markdown/links/* docs/build/man/

即将links/下的别名文件软链接进docs/build/man/，保证别名命令在本地也能通过man正常查阅。

此外 Makefile 还提供几个与文档构建配套的目标：

远程客户端文档构建：remote-docs.sh

docs/remote-docs.sh是远程客户端（remote CLI）文档的组装脚本，它读取docs/source/markdown下的文件，并按目标平台分别格式化。其调用方式为：

docs/remote-docs.sh PLATFORM TARGET SOURCES...

其中：

• PLATFORM：linux、darwin、windows或freebsd
• TARGET：产物暂存目录，例如docs/build/remote/linux
• SOURCES：Markdown 源文件所在目录，例如docs/source/markdown

脚本核心逻辑（详见 docs/remote-docs.sh）包括：

1. 平台分派：darwin/linux/freebsd走man_fn发布器生成.1man 文件；windows走html_fn发布器，借助 pandoc 将 Markdown 转为 HTML。
2. 命令清单自举：通过运行podman help（含子命令递归，podman_all_commands）动态获取全部命令列表，再逐一核对podman-<cmd>.1.md是否存在，缺失即报错退出——这保证了 man 页面与 CLI 实际命令永远同步，也是 CI 会因缺文档而失败的原因。
3. 别名解析：对links/中的.so文件按目标平台展开为真实页面内容；Windows 场景下用sed读取.so man1/xxx指令并定位对应 Markdown。
4. 重命名与改写：rename函数将podman-remote.*产物改名为podman.*，并用sed把内容中的podman-remote替换为podman、Podman for Mac/Podman for Windows等平台化文案，使远程客户端手册呈现为平台本地的podman命令。
5. Windows 附加页：Windows 平台还会额外以 standalone HTML 形式生成 docs/tutorials/podman-for-windows.md 教程页，使用docs/standalone-styling.css样式并内联资源（--self-contained）。

构建 HTML 文档：Sphinx 管线

依赖安装

构建 Sphinx 文档需要 Python 环境。README 中以 Fedora 为例给出依赖安装命令：

$ sudo dnf install python3-sphinx python3-recommonmark $ pip install sphinx-markdown-tables myst_parser

需要说明的是，README 注明上述依赖清单截至 2022-09-15，实际应以 docs/requirements.txt 为准。当前仓库的 requirements.txt 仅包含myst_parser——这是 Read the Docs 构建时 pip 安装的依赖，用于让 Sphinx 直接解析 Markdown（# use md instead of rst）。

执行构建

进入docs/目录后执行：

make html

docs/Makefile是一个标准的 Sphinx 最小 Makefile：SPHINXBUILD ?= sphinx-build、SOURCEDIR = source、BUILDDIR = build，并将所有未知目标透传给sphinx-build -M。这意味着make html实际调用sphinx-build -M html source build。Sphinx 的配置入口是 docs/source/conf.py，而页面组织由 docs/source/index.rst、docs/source/Commands.rst、docs/source/Reference.rst 等 RST 索引文件驱动。

本地预览

构建完成后，产物位于docs/build/html，可用 Python 内置 HTTP 服务器预览：

python -m http.server 8000 --directory build/html

然后浏览器访问http://localhost:8000/。

两个关键的 pandoc Lua 过滤器

remote-docs.sh 在生成 HTML 时会调用两个 Lua 过滤器：

• docs/links-to-html.lua：仅一行核心逻辑，将所有xxx.1.md链接目标改写为xxx.html，让 man 页面间的互相引用在 HTML 化后依然有效。
• docs/use-pagetitle.lua：把文档元数据中的title迁移到pagetitle（阻止 pandoc 自动插入<H1>标题，避免与页面本身的 H1 冲突），并统一追加后缀— Podman documentation，与 Sphinx 生成的 HTML 文档标题风格保持一致。

Man 页面写作规范：MANPAGE_SYNTAX.md

所有 man 页面的格式规范集中在 docs/MANPAGE_SYNTAX.md。这是贡献者编写/修改 man 页面时必须遵守的写作契约，要点包括：

• 章节结构固定：依次为 NAME、SYNOPSIS、DESCRIPTION、OPTIONS、SUBCHAPTER、EXAMPLES、SEE ALSO、HISTORY，每个 man 页面必须以一个空行结尾。
• SYNOPSIS 语义约定：可选参数用[*optional*]包裹，必选参数用*mandatory value*斜体表示；多个候选值用|分隔且两侧必须留空格（*value1* | *value2*）；无限数量参数写作[*value* ...]。
• OPTIONS 写作规则：所有参数统一称 "OPTIONS" 而非 flags；每个 OPTION 用####标题，且必须按字母序排列；默认值用粗体标注，默认布尔值为false；参数多于 3 个时须用表格列出，默认参数必须位于表格首行。
• 术语与链接纪律：不使用代词（尤其禁用you）；引用其他 Podman 页面必须加链接，非 Podman 命令不得链接；路径必须用反引号包裹；只有不属于上述类别的字符串才能高亮（例如不要高亮一个 OPTION 或命令名）。
• 远程客户端限制标注：凡命令/OPTION/内容在远程 Podman 客户端不可用时，须以固定句式说明：IMPORTANT: This command/OPTION/content is not available with the remote Podman client.（写在 DESCRIPTION 中）。
• EXAMPLES 格式：$前缀表示普通用户可执行，#前缀表示仅 root 可执行；注释行使用###前缀。

例如 podman.1.md 中对--events-backend的写法即为规范样例：明确列出允许值file、journald、none，并补充file模式下事件存储路径为<tmpdir>/events/events.log。

API 参考：Swagger 与 Read the Docs 的自动生成

Podman 的 API 文档由 Read the Docs 构建流程自动生成，使用 redoc 渲染swagger.yaml。关键链路记录在仓库根目录的 .readthedocs.yaml：

build: os: ubuntu-26.04 tools: python: "3.14" golang: "1.25" # 至少不低于 test/tools/go.mod 中的 Go 版本，才能构建 swagger jobs: pre_build: - make swagger - mv pkg/api/swagger.yaml docs/source/_static/swagger.yaml sphinx: configuration: docs/source/conf.py formats: - htmlzip - epub - pdf python: install: - requirements: docs/requirements.txt

流程为：pre_build阶段先执行make swagger（其依赖链在 Makefile 中为pkg/api/swagger.yaml: .install.swagger，即先安装 swagger 工具再执行make -C pkg/api），把生成的 pkg/api/swagger.yaml 移入docs/source/_static/，作为静态资源注入 Sphinx 构建，再由 redoc 渲染为在线 API 页面。同时.readthedocs.yaml还额外产出htmlzip、epub、pdf三种格式。

README 还说明了几点使用细节：

• Swagger 文件可下载，latest始终对应 main 分支的最新 YAML；如需特定版本，把latest替换为版本号即可（例如v6.0.0）。
• 该自动化流程自v5.8.4起才启用，更早版本的swagger.yml托管在另一处存储服务中（README 中给出了storage.googleapis.com/libpod-master-releases的存档地址）。

文档质量保障

Podman 仓库对文档的同步与一致性有专门的校验手段（见 Makefile 的文档校验目标）：

这些工具集中在make man-page-check目标下，且在 CI 中（hack/ci/ci.sh）被调用，任何新增命令、选项或 API 若未同步更新文档，都会导致校验失败——这正是 Podman 能长期保持"文档即代码"一致性的工程保证。

小结

从docs/README.md出发可以看到，Podman 的文档体系是一条完整、自动化的生产流水线：以docs/source/markdown/的.1.md/.1.md.in为唯一事实源，分别经make docs（man 手册）、Sphinxmake html（在线 HTML）、docs/remote-docs.sh（三平台远程客户端手册）三条管线产出，再以 Swagger + Redoc 支撑 API 参考，最终由.readthedocs.yaml驱动 Read the Docs 统一发布，并由man-page-check等校验工具保证与 CLI 实现永远同步。对开发者而言，这意味着：修改命令行为时同步更新对应.1.md源文件即可，其余发布环节全部自动化。

【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman