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/目录组织内容目录man 手册的 Markdown 源文件docs/source/markdown/man 手册别名.so 格式链接文件docs/source/markdown/links/构建输出根目录docs/buildman 手册产物docs/build/man远程 Linux man 手册产物docs/build/remote/linux远程 DarwinmacOSman 手册产物docs/build/remote/darwin远程 Windows HTML 页面产物docs/build/remote/windows文档源码的组织方式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 还提供几个与文档构建配套的目标目标说明make docs生成全部 man 手册到docs/build/manmake podman-remote-os-docs生成远程客户端文档见下节make man-page-check组合运行多个人工/自动化文档校验工具make swagger生成pkg/api/swagger.yamlAPI 定义make docker-docs基于 man 手册生成 Docker 兼容文档调用 docs/dckrman.sh远程客户端文档构建remote-docs.shdocs/remote-docs.sh是远程客户端remote CLI文档的组装脚本它读取docs/source/markdown下的文件并按目标平台分别格式化。其调用方式为docs/remote-docs.sh PLATFORM TARGET SOURCES...其中PLATFORMlinux、darwin、windows或freebsdTARGET产物暂存目录例如docs/build/remote/linuxSOURCESMarkdown 源文件所在目录例如docs/source/markdown脚本核心逻辑详见 docs/remote-docs.sh包括平台分派darwin/linux/freebsd走man_fn发布器生成.1man 文件windows走html_fn发布器借助 pandoc 将 Markdown 转为 HTML。命令清单自举通过运行podman help含子命令递归podman_all_commands动态获取全部命令列表再逐一核对podman-cmd.1.md是否存在缺失即报错退出——这保证了 man 页面与 CLI 实际命令永远同步也是 CI 会因缺文档而失败的原因。别名解析对links/中的.so文件按目标平台展开为真实页面内容Windows 场景下用sed读取.so man1/xxx指令并定位对应 Markdown。重命名与改写rename函数将podman-remote.*产物改名为podman.*并用sed把内容中的podman-remote替换为podman、Podman for Mac/Podman for Windows等平台化文案使远程客户端手册呈现为平台本地的podman命令。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 htmldocs/Makefile是一个标准的 Sphinx 最小 MakefileSPHINXBUILD ? 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.yamlbuild: 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 的文档校验目标工具作用hack/man-page-checker检查 man 页面与 CLI 帮助文本是否一致hack/xref-helpmsgs-manpages交叉核对帮助消息与 man 页面hack/xref-quadlet-docs校验 quadlet 相关文档hack/man-page-table-check检查 man 页面中的表格格式hack/swagger-check确保pkg/api/swagger.yaml与 API 实现保持同步swagger-check.t 提供配套测试这些工具集中在make man-page-check目标下且在 CI 中hack/ci/ci.sh被调用任何新增命令、选项或 API 若未同步更新文档都会导致校验失败——这正是 Podman 能长期保持文档即代码一致性的工程保证。小结从docs/README.md出发可以看到Podman 的文档体系是一条完整、自动化的生产流水线以docs/source/markdown/的.1.md/.1.md.in为唯一事实源分别经make docsman 手册、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考