Jazzy与Ruby项目集成：全栈开发的文档生成工具链

Jazzy与Ruby项目集成：全栈开发的文档生成工具链

【免费下载链接】jazzy Soulful docs for Swift & Objective-C 项目地址: https://gitcode.com/gh_mirrors/ja/jazzy

项目概述

Jazzy是一款为Swift和Objective-C项目生成优雅文档的命令行工具，通过解析AST（抽象语法树）实现精准的代码注释提取。其输出风格与Apple官方文档一致，支持数学公式渲染、跨模块链接和自定义主题。作为Ruby gem包，Jazzy可无缝集成到Ruby开发流程中，为全栈项目提供统一的文档解决方案。

核心功能模块

• 文档生成引擎：lib/jazzy/doc_builder.rb
• 符号解析器：SourceKitten/
• 主题系统：lib/jazzy/themes/
• 配置管理：lib/jazzy/config.rb

环境配置

系统要求

• macOS操作系统（推荐版本10.15+）
• Xcode命令行工具或Swift Package Manager
• Ruby 2.6+环境

安装流程

通过RubyGems安装核心组件：

gem install jazzy

项目依赖管理通过Gemfile实现，包含SourceKitten等关键依赖：

gem 'sourcekitten', '~> 0.34'
gem 'redcarpet', '~> 3.5'

基础使用指南

快速启动

在Ruby项目根目录执行：

jazzy --module MyProject --swift-build-tool spm

默认配置下，工具将解析项目中的Swift代码并生成HTML文档至docs/目录。

配置文件示例

创建.jazzy.yaml自定义文档生成规则：

module: MyProject
author: Dev Team
author_url: https://example.com
theme: fullwidth
documentation: Docs/*.md
clean: true
output: ./generated_docs

配置参数说明参见官方文档。

高级集成方案

多模块文档合并

通过--modules参数实现多语言项目文档聚合：

jazzy --modules ModuleA,ModuleB \
      --merge-modules all \
      --output combined_docs

配置示例参见lib/jazzy/grouper.rb中的模块合并逻辑。

数学公式支持

利用KaTeX渲染复杂数学表达式，需在注释中使用特定标记：

/// 二次方程求根公式: `$$x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}$$`
func solveQuadratic(a: Double, b: Double, c: Double) -> (Double, Double)? {
    // 实现代码
}

相关渲染逻辑位于lib/jazzy/extensions/katex/。

自定义主题开发

主题结构

每个主题包含资产文件和Mustache模板：

theme/
├── assets/
│   ├── css/
│   ├── js/
│   └── img/
└── templates/
    ├── doc.mustache
    ├── nav.mustache
    └── ...

默认主题实现参见lib/jazzy/themes/apple/。

样式定制

修改SCSS变量自定义文档外观：

// 自定义主色调
$primary-color: #2c3e50;
// 调整字体大小
$base-font-size: 16px;

编译CSS命令：

sass lib/jazzy/themes/custom/assets/css/jazzy.css.scss:output.css

CI/CD集成

GitHub Actions配置

在.github/workflows/docs.yml中添加文档生成步骤：

jobs:
  build-docs:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: gem install jazzy
      - name: Generate docs
        run: jazzy --config .jazzy.yaml
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Rake任务自动化

创建Rakefile任务简化文档生成：

desc "Generate documentation"
task :docs do
  sh "jazzy --clean --output docs"
end

desc "Open documentation in browser"
task :open_docs => :docs do
  sh "open docs/index.html"
end

执行rake docs即可完成文档构建。

常见问题解决

符号解析失败

• 确保Xcode命令行工具已安装：xcode-select --install
• 检查Swift版本兼容性，通过--swift-version指定版本
• 复杂项目可预生成SourceKitten JSON：

sourcekitten doc -- -workspace MyProject.xcworkspace -scheme MyScheme > doc.json
jazzy --sourcekitten-sourcefile doc.json

主题样式不生效

• 验证主题路径是否正确：--theme ./custom_theme
• 清除缓存文件：rm -rf ~/.cache/jazzy
• 检查CSS编译错误：lib/jazzy/themes/apple/assets/css/jazzy.css.scss

扩展阅读

• 多语言支持：ObjectiveC.md
• 符号图生成：lib/jazzy/symbol_graph/
• 贡献指南：CONTRIBUTING.md

通过jazzy --help config查看完整配置选项，或提交issue至项目仓库获取支持。

【免费下载链接】jazzy Soulful docs for Swift & Objective-C 项目地址: https://gitcode.com/gh_mirrors/ja/jazzy