Skia 官方文档构建指南：使用 Doxygen 从源码生成 2D 图形库 API 文档

图形学【免费下载链接】skiaSkia is a complete 2D graphic library for drawing Text, Geometries, and Images. See documentation for contribution instructions.项目地址https://gitcode.com/gh_mirrors/ski/skia点击查看免费下载本篇指南围绕 Skia 仓库中 tools/doxygen/README.md 展开系统讲解如何利用 Doxygen 将 Skia 的 C 头文件与源码注释编译成完整的 HTML API 文档从环境安装、一条命令生成、本地浏览器预览到使用entr实现保存即重生成的开发模式再到仓库中 Doxyfile 各项关键配置的源码级解读。读完本文你将能够在本地完整复现 Skia 官方文档站的生成流程并理解其输入范围、预处理策略与图形渲染背后的原理。快速上手一条命令生成全部文档Skia 在仓库的tools/doxygen目录中预先配置好了完整的 Doxygen 工程Doxyfile因此生成全部文档只需一条命令。首先进入该目录然后执行cd tools/doxygen doxygen DoxyfileDoxygen 会依据Doxyfile中的INPUT配置扫描 Skia 的公开头文件与文档源文件并在指定的输出目录中生成全套 HTML 文档。依据 tools/doxygen/Doxyfile 中的OUTPUT_DIRECTORY /tmp/doxygen配置所有产物会写入/ttmp/doxygen其中 HTML 页面位于html子目录由HTML_OUTPUT html决定见 tools/doxygen/Doxyfile。注意README 中给出的是/tmp/doxygen这是Doxyfile中写死的绝对路径。如果你不希望向/tmp写入文件可以直接修改OUTPUT_DIRECTORY或参考下文CI 场景下的配置覆盖一节用追加配置的方式覆盖它。在浏览器中本地预览生成完成后HTML 文件是纯静态页面直接用浏览器打开index.html也可查看但更推荐用 Python 内置的 HTTP 服务器在本地提供服务这样搜索、树形导航等依赖相对路径的功能才能正常工作cd /tmp/doxygen/html python3 -m http.server 8000然后访问http://localhost:8000http.server是 Python 3 标准库自带的模块无需安装任何额外依赖。如果想换端口把8000换成其他空闲端口即可。环境准备安装 Doxygen生成文档的前提是机器上安装了 Doxygen 工具。README 给出的是 Linux 桌面环境的安装方式sudo apt install doxygen这是 Ubuntu/Debian 系发行版的安装命令。对于其他系统可以对照使用对应的包管理器系统安装命令示例Ubuntu / Debiansudo apt install doxygenFedora / RHELsudo dnf install doxygenmacOSHomebrewbrew install doxygenWindows使用官方安装包或choco install doxygen另外需要说明的是Skia 的 Doxyfile 中HAVE_DOT YES即默认启用了 Graphviz 的dot工具来绘制类继承图、包含关系图等对应CLASS_GRAPH、INCLUDE_GRAPH、INCLUDED_BY_GRAPH、DIRECTORY_GRAPH等均为YES见 tools/doxygen/Doxyfile。如果系统中没有 Graphviz文档生成仍会继续但会缺少这些图形化关系图。建议一并安装sudo apt install graphviz开发模式保存即自动重新生成在编写、修改 Skia 头文件中的 Doxygen 注释时频繁手动重跑doxygen命令很低效。README 提供了一种基于entr文件变更监视器的方案监听include/与src/目录下所有文件一旦有保存操作就自动重新运行 Doxygen。安装 entrsudo apt install entr启动自动重建在tools/doxygen目录下执行find ../../include/ ../../src/ . | entr doxygen ./Doxyfile命令拆解find ../../include/ ../../src/ .列出include/、src/以及当前目录tools/doxygen下的所有文件。其中include/下主要是 Doxygen 的输入头文件INPUT指向的核心目录之一src/是 Skia 的实现源码而当前目录下的Doxyfile、mainpage/mainpage.dox等配置文件本身发生变化时也应触发重建entr读取标准输入中的文件列表持续监视这些文件当其中任何一个文件被修改保存时执行其后指定的命令doxygen ./Doxyfile。运行后终端会保持前台监听状态。此时编辑任意被监视的头文件并保存文档便会自动重建非常适合边改注释边对照渲染结果的工作流。停止监听可按CtrlC。读懂 Skia 的 Doxyfile文档生成的控制台doxygen Doxyfile之所以能生成出符合 Skia 官方风格的文档是因为 tools/doxygen/Doxyfile 这份 2500 余行的配置承载了大量精心调校的选项。下面选取与文档内容、范围和质量最相关的几组核心配置进行解读。项目标识与输出目录PROJECT_NAME Skia PROJECT_BRIEF 2D Graphics Library PROJECT_LOGO logo.png OUTPUT_DIRECTORY /tmp/doxygenPROJECT_NAME出现在每个生成页面标题中的项目名tools/doxygen/DoxyfilePROJECT_BRIEF显示在页面顶部的单行简介tools/doxygen/DoxyfilePROJECT_LOGO指向 tools/doxygen/logo.pngDoxygen 会把它复制到输出目录并显示在页面头部OUTPUT_DIRECTORY所有输出产物的根目录tools/doxygen/Doxyfile。输入范围INPUT 决定了文档覆盖哪些代码这是理解Skia 官方文档包含什么的关键。INPUT配置tools/doxygen/Doxyfile如下INPUT ../../include/core \ ../../include/effects \ ../../include/docs \ ../../include/gpu \ ../../include/pathops \ ../../third_party/skcms \ ../../modules/skottie/include \ ../../modules/sksg/include \ ../../modules/skshaper/include \ ../../modules/svg/include \ ./mainpage也就是说Skia 的 API 文档并非覆盖整个仓库而是有选择性地收录核心公开 APIinclude/core绘制、画布、图像、颜色等基础类型、include/effects图像滤镜与特效、include/gpuGPU 后端公开接口、include/pathops路径布尔运算颜色管理third_party/skcmsSkia 使用的紧凑色彩管理库模块化子库modules/skottie/includeLottie 动画、modules/sksg/include场景图、modules/skshaper/include文本整形、modules/svg/includeSVG 渲染手写文档页./mainpage目录其中的 mainpage/mainpage.dox 定义了文档主页\mainpage块的内容包括项目定位、许可证说明与外部资源索引。路径中的../../是相对于tools/doxygen目录的写法实际指向仓库根下的对应目录。如果希望文档覆盖更多模块例如include/utils或modules/canvaskit修改INPUT后重新运行即可。FILE_PATTERNStools/doxygen/Doxyfile则限定了在这些目录内只解析常见源码与文档扩展名.c/.cpp/.h/.mm/.md/.dox等RECURSIVE NOtools/doxygen/Doxyfile表示不递归扫描子目录——所以上面的INPUT把每个目标头文件目录都显式列了出来。文档完整性相关配置EXTRACT_ALL YES EXTRACT_STATIC YES EXTRACT_LOCAL_CLASSES YES BRIEF_MEMBER_DESC YES REPEAT_BRIEF YES ALWAYS_DETAILED_SEC YES JAVADOC_AUTOBRIEF YES MULTILINE_CPP_IS_BRIEF YESEXTRACT_ALL YEStools/doxygen/Doxyfile即使某个实体没有 Doxygen 注释也会被收录进文档只是没有说明文字保证 API 覆盖面完整EXTRACT_STATIC YEStools/doxygen/Doxyfile文件内static成员也会出现在文档中JAVADOC_AUTOBRIEF YEStools/doxygen/DoxyfileJavadoc 风格注释的第一句话到第一个句号为止自动作为 brief 描述ALWAYS_DETAILED_SEC YEStools/doxygen/Doxyfile只有 brief 描述的成员也会生成详细说明小节。这几项组合起来保证了庞大的include/core等目录即使存在注释不完整的头文件生成的 API 参考也不会出现大面积缺页。预处理与宏展开为 C 代码正确解析铺路Skia 的源码大量使用条件编译宏例如调试专用的SkDEBUGCODE如果不做预处理Doxygen 的解析器可能被宏结构干扰。Doxyfile对应配置为ENABLE_PREPROCESSING YES MACRO_EXPANSION YES EXPAND_ONLY_PREDEF YES EXPAND_AS_DEFINED SkDEBUGCODE SKIP_FUNCTION_MACROS YESENABLE_PREPROCESSING YEStools/doxygen/Doxyfile解析前先执行 C 预处理器指令MACRO_EXPANSION YEStools/doxygen/Doxyfile展开源码中的宏EXPAND_ONLY_PREDEF YES与EXPAND_AS_DEFINED SkDEBUGCODEtools/doxygen/Doxyfile只展开白名单宏将SkDEBUGCODE这类仅存在于调试构建中的宏展开为空避免解析器把函数声明与定义拆散SKIP_FUNCTION_MACROS YEStools/doxygen/Doxyfile跳过全大写函数式宏防止样板代码干扰解析。HTML 输出与视觉定制GENERATE_HTML YES HTML_OUTPUT html GENERATE_TREEVIEW YES SEARCHENGINE YES HTML_FOOTER ./footer.html HTML_EXTRA_STYLESHEET ./customdoxygen.cssGENERATE_TREEVIEW YEStools/doxygen/Doxyfile在页面左侧生成可折叠的树形导航SEARCHENGINE YEStools/doxygen/Doxyfile生成客户端 JavaScript 全文搜索框HTML_FOOTER ./footer.htmltools/doxygen/Doxyfile使用仓库自带的 tools/doxygen/footer.html 作为页脚模板其中引入了 markdeep 脚本用于增强排版HTML_EXTRA_STYLESHEET ./customdoxygen.csstools/doxygen/Doxyfile加载 Skia 定制的 tools/doxygen/customdoxygen.css该样式表定义了 Skia 品牌色变量蓝色主调rgb(0,114,178)等并覆盖了标题区、代码片段、导航路径等默认外观使文档站与 Skia 视觉风格保持一致与之对应LaTeX 输出被显式关闭GENERATE_LATEX NO见 tools/doxygen/DoxyfileRTF、XML、Docbook 等输出格式同样处于关闭状态说明这份配置的目标产物就是 HTML。图形与性能相关配置HAVE_DOT YES CLASS_GRAPH YES INCLUDE_GRAPH YES INCLUDED_BY_GRAPH YES DIRECTORY_GRAPH YES DOT_GRAPH_MAX_NODES 50 LOOKUP_CACHE_SIZE 8HAVE_DOT YEStools/doxygen/Doxyfile与CLASS_GRAPH YES等选项利用 Graphviz 生成类继承图、包含关系图、目录依赖图DOT_GRAPH_MAX_NODES 50tools/doxygen/Doxyfile单个图中最多显示 50 个节点防止继承关系过大的类图失控LOOKUP_CACHE_SIZE 8tools/doxygen/Doxyfile将符号查找缓存增大到2^(168)条目以加速对 Skia 这种大体量 C 代码的解析。官方文档站是如何生成的CI 流水线中的 ProdDoxyfiletools/doxygen目录下还有一份 ProdDoxyfile其内容如下# This config is used to generate the docs under continuous integration. INCLUDE Doxyfile OUTPUT_DIRECTORY $(OUTPUT_DIRECTORY)这份生产配置没有重复定义全部选项而是通过 Doxygen 的INCLUDE指令复用主Doxyfile仅用OUTPUT_DIRECTORY覆盖输出路径值来自命令行传入的-D宏或 CI 环境变量从而保证本地生成与CI 生成使用同一套文档规则只是落盘位置不同。这是 Doxygen 配置复用的典型实践。仓库的 CI 侧infra/bots提供了完整的自动化实现可以印证这套流程在真实环境中如何运转infra/bots/recipe_modules/doxygen/resources/generate_and_upload_doxygen.py 中定义了generate_and_upload_doxygen()它先在工作目录复制一份Doxyfile并追加OUTPUT_DIRECTORY与HTML_FOOTER覆盖项然后调用doxygen生成文档最后用gcloud storage cp将产物上传到gs://skia-doc/doxygen公开桶上游 recipe 封装 infra/bots/recipe_modules/doxygen/api.py 通过generate_and_upload(skia_dir)在 Skia 根目录执行该脚本调度入口是 infra/bots/recipes/housekeeper.py 中的 housekeeper 任务generate and upload doxygen 步骤也就是说 Skia 官方文档站由持续集成任务定期生成并发布。从源码结构可以推断本地doxygen Doxyfile的产物与 CI 上传的官方文档来自同一份Doxyfile规则唯一差别是输出目录和页脚文件被 CI 脚本覆盖——这也是为什么官方文档与本地生成结果高度一致。常见问题与排错Q1命令报doxygen: command not found说明 Doxygen 未安装先执行上文环境准备中的安装命令然后重新运行。Q2生成了文档但没有类图/关系图检查 Graphviz 是否安装which dot。HAVE_DOT YES时若找不到dotDoxygen 会跳过图形生成并给出警告。Q3文档缺少某些模块的 API查看 tools/doxygen/Doxyfile 的INPUT列表确认该模块的头文件目录是否在列。Skia 的 Doxygen 文档是有选择地覆盖include/core、include/effects、include/gpu、include/pathops及各模块include子目录的公开 API。Q4希望修改输出目录不要直接改动仓库文件可以在tools/doxygen下新建一个本地配置文件并追加覆盖例如INCLUDE Doxyfile OUTPUT_DIRECTORY ./out/docs然后执行doxygen MyDoxyfile。这种方式与ProdDoxyfile的INCLUDE用法一致不会影响仓库内容。Q5文档是英文的能否改语言OUTPUT_LANGUAGE Englishtools/doxygen/Doxyfile控制的是 Doxygen 生成的固定 UI 文案如 Class Reference 等改为Chinese可切换界面语言但源码注释本身的内容不会变。Q6entr监听模式不触发重建确认命令是在tools/doxygen目录下执行的且find列出的路径../../include/、../../src/相对该目录有效另外确保正在编辑的文件确实位于被监听列表内。小结Skia 的 Doxygen 文档体系由三部分构成入口文档 tools/doxygen/README.md 负责使用说明tools/doxygen/Doxyfile 是完整的生成配置tools/doxygen/mainpage/mainpage.dox 定义主页内容。日常使用只需两条命令——doxygen Doxyfile生成、python3 -m http.server预览开发期可借助entr实现保存即重建。若需要深入定制调整覆盖范围、视觉风格或接入 CIDoxyfile中INPUT、HTML_EXTRA_STYLESHEET、INCLUDE机制以及 infra/bots 下的 CI 脚本都是可以直接参考的现成范例。赞分享图形学【免费下载链接】skiaSkia is a complete 2D graphic library for drawing Text, Geometries, and Images. See documentation for contribution instructions.项目地址https://gitcode.com/gh_mirrors/ski/skia点击查看免费下载相关推荐Android-PickerView 源码文档生成使用Doxygen创建API文档Android PickerView 源码文档生成使用Doxygen创建API文档 1. 引言为什么需要API文档 在Android开发中高质量的API移动开发UI组件FlatBuffers 官方文档生成全指南基于 Doxygen 与 doxypypy 构建 API 参考文档FlatBuffers 官方文档生成全指南基于 Doxygen 与 doxypypy 构建 API 参考文档 本篇指南围绕 FlatBuffers 源码树中的人工智能大模型推理引擎深度学习本地部署模型量化模型优化多模态计算机视觉嵌入式Soundflower代码文档生成使用Doxygen创建API参考文档Soundflower代码文档生成使用Doxygen创建API参考文档 1. 引言为什么需要API文档 你是否曾在接手一个没有文档的项目时感到无从下手是驱动开发音视频上一篇ComfyUI-Easy-Use如何彻底解决AI图像生成中的GPU显存泄漏难题下一篇如何实现智能GPU资源管理ComfyUI-Easy-Use高效优化指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考