抄近道。 大家好啊。今天我们要讲的是那个很麻烦的iOS文档生成。就是那个Jazzy。很多人用不了主要原因是它报错了。报错就像那个...让人头大的事情。所以今天我就来写一写怎么解决这个问题。顺便说说怎么生成文档。其实很简单，但是很多人不知道。特别是那些刚学iOS的。他们总是搞不懂Ruby是什么。Ruby是啥？Ruby就是那个...嗯...编程语言。我们iOS开发要用到它。主要原因是Jazzy是用Ruby写的。对，就是这么个关系。

为什么我们要用Jazzy？

不夸张地说... 主要原因是iOS的文档很难看。Xcode自带的文档有时候看不懂。而且很慢。所以大家就想用Jazzy。Jazzy能生成很漂亮的网页文档。就像那个...API文档一样。很清晰。而且支持Markdown。就是写文章用的那个格式。你可以在文档里写很多废话。或者写很多有用的东西。只要你愿意。反正都能写进去。这对于团队开发很重要。不然别人看了你的代码。根本不知道你在干嘛。比如你写了一个函数叫 `func eatApple`。别人不知道这个函数是干嘛的。但是如果你写了文档。别人就知道。哦，原来这个函数是用来吃苹果的。这就是文档的好处。

但是Jazzy的安装过程真的很烦人。它不像其他的包管理工具那么简单。比如CocoaPods。那个就很简单。一行命令就搞定了。但是Jazzy不是。它需要Ruby。还需要Gem。Gem是什么？Gem就是Ruby的插件。对，就是插件。你需要安装这个插件。然后才能安装Jazzy。 话虽然是这么说… 如果你没有安装Ruby。那就更麻烦了。你需要去官网下载Ruby。然后配置环境变量。这个过程非常长。很多人看到这里就放弃了。真的。我见过很多人。他们说：“算了不搞了。” 然后就去写代码了。但是不写文档。代码写得乱七八糟。再说说只有自己看得懂。

所以今天我们就来详细讲一下。怎么安装Jazzy。怎么解决那个报错。怎么生成文档。希望对大家有帮助。 琢磨琢磨。 如果你是小白。请仔细看。如果你是大神。请无视我。或者给我点个赞。谢谢了。

安装前的准备工作

对吧？ 在开始之前。你需要确认几件事。，你需要打开终端。终端是什么？就是那个黑黑的窗口。在Launchpad里找。或者用Spotlight搜索Terminal。如果你找不到。那你真的需要去上点课了。

好了。准备工作做完了。我们就可以开始安装Jazzy了。但是等等。安装过程中。你会遇到一个很大的坑。那个坑就是刚才说的那个报错。那个报错真的很长。很长很长。就像一篇文章一样。如果你看到那个报错。不要慌。不要慌。深呼吸。冷静一下。那个报错的意思是。你的电脑里缺少了Ruby的头文件。什么头文件？就是那些 `.h` 文件。

C语言用的。Ruby也是C语言写的。所以它也需要头文件。如果你没有这些文件。Gem就无法编译那个Redcarpet插件。Redcarpet是干嘛的？它是用来解析Markdown的。 别怕... 没有它。Jazzy就不知道怎么把你的Markdown转换成HTML。所以如果你看到那个报错。就说明你的Ruby开发环境没装好。

遇到那个长报错怎么办？

PTSD了... 让我们来看看那个报错。那个报错真的很经典。很多人都会遇到。我把它贴在这里。大家仔细看。

ERROR: Failed to build gem native extension.
    current directory: /Library/Ruby/Gems/2.6.0/gems/redcarpet-3.5.0/ext/redcarpet/System/Library/Frameworks//Versions/2.6/usr/bin/ruby -I /System/Library/Frameworks//Versions/2.6/usr/lib/ruby/2.6.0 -r ./siteconf20190906-93824-
    can't find header files for ruby at /System/Library/Frameworks//Versions/2.6/usr/lib/ruby/include/ might have to install separate package for  ruby developmentenvironment, ruby-dev or ruby-devel for
    failed, exit code 1Gem files will remain installed in /Library/Ruby/Gems/2.6.0/gems/redcarpet-3.5.0 for
    logged to /Library/Ruby/Gems/2.6.0/extensions/universal-darwin-19/2.6.0/redcarpet-3.5.0/gem_

看懂了吗？看不懂也没关系。反正意思就是“找不到Ruby头文件”。那个路径 `/System/Library/Frameworks//Versions/2.6/usr/lib/ruby/include/` 看起来很复杂。其实它只是说。 换个角度。 它在这个地方找。但是没找到。所以它就报错了。那个 `exit code 1` 也很重要。这意味着命令施行失败了。所以你后面的命令都别想跑了。你必须先解决这个问题。这个问题怎么解决？其实很简单。就是安装那个Ruby开发包。

在Mac上。怎么安装Ruby开发包呢？你需要用Homebrew。对，还是Homebrew。主要原因是Mac自带的Ruby不太好用。而且没有开发包。你需要安装一个叫 `ruby-build` 的东西。然后指定版本安装。或者你可以直接安装一个更高级的Ruby版本。比如用rbenv。rbenv是管理Ruby版本的。很方便。你可以安装Ruby 2.6。也可以安装Ruby 3.0。随便你。但是为了解决这个报错。你最好安装一个完整的Ruby环境。

解决方法：安装Jazzy

试着... 解决完那个报错之后。我们就可以安装Jazzy了。安装Jazzy的命令非常简单。就是一行。但是这一行里有很多参数。我们一个个来看。

sudo gem install jazzy -n /usr/local/bin --verbose

这个命令是干嘛的？`sudo` 是什么意思？是超级用户。就是管理员的意思。主要原因是安装软件需要权限。所以要用sudo。`gem install jazzy` 是安装Jazzy这个Gem。`-n /usr/local/bin` 是什么意思？这个参数很重要。它指定了安装的路径。`/usr/local/bin` 是一个很重要的目录。 嚯... 所有的全局命令都应该安装在这里。这样你在任何地方都可以调用Jazzy。如果你不加这个参数。Jazzy可能会安装在别的地方。比如 `~/.gem/ruby/2.6.0/bin`。然后你每次用的时候。都要输入完整路径。很麻烦。所以一定要加这个参数。

好吧... 还有一个参数是 `--verbose`。这个参数是干嘛的？它是“详细模式”的意思。如果你加了这个参数。终端就会输出很多信息。比如它在下载什么。它在编译什么。它在安装什么。这对于排错非常有用。如果你遇到问题。加上这个参数。你就能看到更多的信息。也许就能找到原因。所以。强烈推荐加上这个参数。除非你非常熟悉这个过程。不然就加上吧。

站在你的角度想... 施行完这个命令之后。你会要求输入密码。输入你的Mac的登录密码。密码是看不见的。你打进去就行。输完按回车。然后它就开始下载。下载完成之后。它会自动编译和安装。这个过程可能需要几分钟。取决于你的网速。网速快的话。一秒钟就搞定了。网速慢的话。可能要等半天。如果你看到 `Successfully installed`。那就说明安装成功了。如果你看到 `ERROR`。那就说明还有问题。你需要重新看上面的报错。

开始生成文档

安装好了Jazzy。我们就可以开始生成文档了。但是先说说。你需要进入你的工程目录。 换句话说... 对，就是你的代码所在的文件夹。你需要用 `cd` 命令进入这个文件夹。

cd /Users/yusheng/Desktop/Jazzy

没耳听。 这个命令的意思是。Change Directory。改变目录。进入 `/Users/yusheng/Desktop/Jazzy` 这个路径。这个路径是你电脑上的一个路径。你需要改成你自己的路径。比如你的代码在桌面上。那你就输入 `cd Desktop`。然后回车。进入桌面之后。再用 `ls` 命令看看有哪些文件。找到你的项目文件夹。然后用 `cd` 进入它。

白嫖。 进入工程目录之后。你就可以施行Jazzy命令了。最简单的命令就是 `jazzy`。但是这个命令生成的文档可能不太好看。也不太符合你的要求。所以。我们需要加一些参数。最常用的参数就是 `--min-acl internal`。这个参数是干嘛的？它设置文档的访问权限。`internal` 是内部的意思。这意味着生成的文档默认是私有的。只有你的团队成员可以看。如果你想让所有人都能看。你可以改成 `public`。或者 `public` 和 `internal` 都写上。

还有一个很重要的参数是 `--swift-version`。这个参数指定了Swift的版本。比如 `--swift-version 4.1.2`。这个版本号很重要。如果你的代码是用Swift 4.1.2写的。但是你指定的是Swift 5.0。 脑子呢？ 那生成的文档可能就不准确了。主要原因是Swift 5.0有很多新的特性。4.1.2可能不支持。所以。一定要选对版本号。怎么知道你用的是哪个版本？看你的Xcode项目设置。或者在代码里用 `@available` 标记。

jazzy --min-acl internal# 选择 Swift 语言版本jazzy --swift-version 4.1.2 --min-acl internal

看。这就是两个命令。第一个命令比较简单。第二个命令指定了Swift版本。你可以根据你的需要选择。施行完这两个命令之后。你会发现你的工程目录里多了一个 `docs` 文件夹。打开这个文件夹。里面就是生成的HTML文件。你可以用浏览器打开。那个 `index.html` 就是主页。非常漂亮。而且支持搜索。支持代码高亮。非常好用。

常见问题

虽然安装过程看起来很简单。但是其实吧。你会遇到很多问题。这些问题都很让人头大。特别是对于新手。下面我列几个常见的问题。希望你能遇到。不希望你不要遇到。但是万一遇到了。你知道怎么解决，归根结底。。

1.安装问题

这个是最常见的问题。就是那个报错。找不到Ruby头文件。这个问题怎么解决？我有两个办法。第一个办法是。用Homebrew安装一个完整版的Ruby。比如 `brew install ruby`。然后设置环境变量。让系统使用这个Ruby。第二个办法是。安装Xcode命令行工具。命令是 `xcode-select --install`。这个工具包含了Ruby的开发包。安装完这个工具之后。再试试安装Jazzy。应该就可以了。

还有一个安装问题。就是权限问题。如果你没有用 `sudo`。可能会报错说没有权限。这个很简单。加上 `sudo` 就行了。但是要注意。 可不是吗！ 不要随便用 `sudo`。主要原因是 `sudo` 可以做很多事情。比如删除系统文件。所以用的时候要小心。最好知道你在干什么。

2.命令行找不到Jazzy

有时候。你安装好了Jazzy。但是你在终端输入 `jazzy`。系统说找不到命令。这是怎么回事？这是主要原因是Jazzy没有安装到系统默认的PATH里。比如你安装到了 `/usr/local/bin`。但是你的PATH里没有这个路径。解决方法也很简单。就是把 `/usr/local/bin` 加到你的PATH里。或者。你每次使用Jazzy的时候。都输入完整路径。比如 `/usr/local/bin/jazzy`。虽然麻烦。但是能解决问题。

3.文档生成失败

有时候。你施行了 `jazzy` 命令。但是它报错了。比如找不到类。或者找不到方法。这通常是主要原因是你的代码里有注释错误。或者你的注释格式不对。Jazzy是根据注释生成文档的。如果你的注释写错了。它就生成不了文档。所以。一定要写好注释。使用标准的格式。比如 `///` 开头的注释。或者 `/** ... */` 格式的注释。

还有一个原因。可能是你的Swift版本太老了。或者太新了。Jazzy可能不支持最新的Swift版本。 YYDS... 或者不支持旧的版本。所以。你需要检查一下Jazzy的文档。看看它支持哪些Swift版本。

4.如何定制文档样式

默认的文档样式可能不是你想要的。你想要一个更酷炫的样式。或者更符合你公司品牌颜色的样式。怎么办？Jazzy支持自定义主题。你可以写自己的CSS文件。或者用HTML模板。 躺平。 这需要一定的前端知识。如果你不会。那就只能用默认的样式了。或者。你可以找一些现成的主题。网上有很多。比如Dark主题。或者Light主题。

好了。今天讲了这么多。其实就是讲怎么安装Jazzy。怎么解决那个报错。怎么生成文档。过程虽然有点繁琐。但是后来啊是很漂亮的。文档生成之后。你的代码就变得专业了。别人看你的代码。会觉得很舒服。你也会觉得很舒服。写文档虽然很累。但是值得，YYDS！。

希望这篇文章能帮到你。如果你觉得有用。请转发一下。让更多人看到。如果你觉得没用。也请告诉我。我会继续努力的。毕竟我水平有限。写得不好。请见谅。下次我们再聊别的。 往白了说... 比如怎么优化iOS应用的启动速度。或者怎么做一个很漂亮的UI。那个也很重要。但是今天先到这儿吧。我要去吃苹果了。真的。我写了一个吃苹果的函数。哈哈。

再说说。 强调一下那个命令。`sudo gem install jazzy -n /usr/local/bin --verbose`。一定要记住。这可是关键。还有那个 `jazzy --swift-version 4.1.2 --min-acl internal`。也记一下。以后肯定用得上。别到时候又来问我。我可不告诉你第二次。开玩笑的。我可以告诉你第三次。但是第四次我就不耐烦了，我算是看透了。。

试着... 好了。不说了。我要去写代码了。我的代码现在还没有文档。我要赶紧用Jazzy生成一个。不然明天老板问起来。我又得瞎编。希望我的老板不会用Jazzy。不然他就知道我在瞎编了。嘿嘿。祝大家开发顺利。再见。