{% github realm jazzy 6932e5e width = 30% %}

demo {% github appcoda SwiftDocSample 24c1649 width = 30% %}

使用 Jazzy 产生代码文档

Jazzy 是一款可以为 Swift 和 Objective-C 代码产生具有 Apple 风格的代码文档工具。事实上，Jazzy 会为你创建一个链接所有代码文档的独立网页。它是一款命令行工具，但还是很容易使用的。 在 Xcode 中使用 Markdown 生成 Swift 代码文档

安装

1

$ sudo gem install jazzy

gem source不稳定常会导致无法找到jazzy

1
2
3
4

$ gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
$ gem sources -l
https://gems.ruby-china.com
# 确保只有 gems.ruby-china.com

腾讯云： https://gems.ruby-china.com/ 淘宝：https://ruby.taobao.org/

使用

使用 cd 命令将目录切换到工程对应的目录：

1
2

cd path_to_project_folder
Jazzy

输入 Jazzy 之后敲回车,会将标注为 public 的结构写入代码文档。 如果你想要包含所有的实体，就输入一下：

1

jazzy --min-acl internal

默认输出的文件夹位于工程的根目录（你也可以更改输出路径），叫 docs。 当jazzy不支持swift版本时，会导致错误：

1
2

Could not parse compiler arguments from `xcodebuild` output.
Please confirm that `xcodebuild` is building a Swift module.

这是就需要在build settings中设置swift Language Version版本号。

生成指定的swift版本

如果不是 Swift 的最新版本，发现使用 Jazzy 后没有效果的话，需要先指定 Xcode 支持的 Swift 版本：

1

jazzy --swift-version 2.1.1 --min-acl internal

帮助

jazzy -help查看使用 Jazzy 时可能使用到的参数。当然，你完全可以根据自己的喜好来得到最终的结果。

集成Xcode

在项目中添加运行脚本，或创建 其他–>Aggregate在build phases下添加New run script phase

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

author="iTBoyer";
author_url="http://it-boyer.github.io";
github_url="https://github.com/it-boyer";
sdk="iphone";
output="docs/swift_output";   #生成的文档地址
docSetDir="/Users/admin/Library/Developer/Shared/Documentation/DocSets/"

jazzy \
--objc \
--clean \
--author "${author}"\
--author_url "${author_url}" \
--github_url "${github_url}" \
--module-version 0.96.2 \
--xcodebuild-arguments -scheme,"${PROJECT_NAME}" \
--module "${PROJECT_NAME}" \
--sdk  "${sdk}" \
--output "${output}" \
#拷贝到xcode文档目录中
echo "${output}/docsets/${PROJECT_NAME}.docset"
pwd
cp -r "${output}/docsets/${PROJECT_NAME}.docset" "${docSetDir}"

安装到Xcode，在编写代码时，可以快速查看帮助。

1
2
3
4

#拷贝到xcode文档目录中
echo "${output}/docsets/${PROJECT_NAME}.docset"
pwd
cp -r "${output}/docsets/${PROJECT_NAME}.docset" "${docSetDir}"

工具推荐

  • appledoc工具install 方法和更新方法相同
1
2
3

git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh