swift 使用Jazzy 生成代码文档

iOS中能生成文档的有HeaderDoc、AppleDoc、Doxygen、Jazzy等，但是HeaderDoc、AppleDoc、Doxygen都不支持swift（至少目现在是这样），所以最后选择了Jazzy。

Jazzy 是一款可以为 Swift 和 Objective-C 代码产生具有 Apple 风格的代码文档工具.对于如何使用markdown对代码进行注释以及对Jazzy的介绍可以参考原文链接

jazzy具体使用方法可以去访问 Github页面，安装方法如下：

1. 打开“终端”
2. 输入“sudo gem install jazzy”
3. 输入密码
4. 等待

$ cd path_to_project_folder

然后执行

$ jazzy --min-acl internal

然后在终端就会看到

$ jam out ♪♫ to your fresh new docs in docs

默认输出的文件夹位于工程的根目录（你也可以更改输出路径），叫 docs。
使用 Finder 进入到对应路径，在浏览器中打开 index.html。你立即就会发现，默认生成的页面风格和 Apple 官方文档是非常相似的。如果不出问题到此就完成了。

说一下我在安装过成中遇到的坑
第一个问题：

ERROR: SSL verification error at depth 1: unable to get local issuer certificate (20)
ERROR: You must add /O=Digital Signature Trust Co./CN=DST Root CA X3 to your local trusted store
ERROR: SSL verification error at depth 1: unable to get local issuer certificate (20)
ERROR: You must add /O=Digital Signature Trust Co./CN=DST Root CA X3 to your local trusted store
ERROR: SSL verification error at depth 2: self signed certificate in certificate chain (19)
ERROR: Root certificate is not trusted (/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA)
Fetching: liferaft-0.0.6.gem (100%)
Successfully installed liferaft-0.0.6
Fetching: xcinvoke-0.3.0.gem (100%)
Successfully installed xcinvoke-0.3.0
Fetching: sass-3.4.24.gem (100%)
ERROR: While executing gem ... (Errno::EPERM)
Operation not permitted - /usr/bin/sass

这个问题是因为需要安装或者升级ruby，然后重新执行sudo gem install jazzy就可以了
ruby安装：

$ curl -L get.rvm.io | bash -s stable
$ source ~/.bashrc
$ source ~/.bash_profile

查看当前ruby版本

$ rvm -v

列出已知的 Ruby 版本

$ rvm list known

比如更新ruby到2.4.0

$ rvm install 2.4.0

更新后就可以继续执行sudo gem install jazzy了

第二个问题：当我执行Jazzy时

Running xcodebuild
Could not parse compiler arguments from xcodebuild output.
Please confirm that xcodebuild is building a Swift module.
Saved xcodebuild log file: /var/folders/xz/7jvsntw524vc5vlzk7lqwml40000gn/T/xcodebuild-5E0C5A75-D91F-497C-AF96-08C9CC28E796.log
Failed to generate documentation
/Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/executable.rb:36:in execute_command': /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/bin/sourcekitten ["doc", "--"] (RuntimeError) Running xcodebuild Could not parse compiler arguments fromxcodebuildoutput. Please confirm thatxcodebuildis building a Swift module. Savedxcodebuildlog file: /var/folders/xz/7jvsntw524vc5vlzk7lqwml40000gn/T/xcodebuild-5E0C5A75-D91F-497C-AF96-08C9CC28E796.log Failed to generate documentation from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/sourcekitten.rb:217:inrun_sourcekitten'
from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/doc_builder.rb:67:in block in build' from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/doc_builder.rb:65:inchdir'
from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/doc_builder.rb:65:in build' from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/bin/jazzy:15:in'
from /Users/XXXX/.rvm/rubies/ruby-2.4.0/bin/Jazzy:23:in load' from /Users/XXXX/.rvm/rubies/ruby-2.4.0/bin/Jazzy:23:in
'
from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/bin/ruby_executable_hooks:15:in eval' from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/bin/ruby_executable_hooks:15:in
'

只需要把项目commond + R 编译一下就行了

swift 使用Jazzy 生成代码文档

你可能感兴趣的:(swift 使用Jazzy 生成代码文档)