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
到项目根目录下:
$ 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 fromxcodebuild
output.
Please confirm thatxcodebuild
is building a Swift module.
Savedxcodebuild
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:inexecute_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 from
xcodebuildoutput. Please confirm that
xcodebuildis building a Swift module. Saved
xcodebuildlog 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:in
run_sourcekitten'
from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/doc_builder.rb:67:inblock in build' from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/doc_builder.rb:65:in
chdir'
from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/lib/jazzy/doc_builder.rb:65:inbuild' from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/gems/jazzy-0.8.2/bin/jazzy:15:in
<top (required)>'
from /Users/XXXX/.rvm/rubies/ruby-2.4.0/bin/Jazzy:23:inload' from /Users/XXXX/.rvm/rubies/ruby-2.4.0/bin/Jazzy:23:in
<main>'
from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/bin/ruby_executable_hooks:15:ineval' from /Users/XXXX/.rvm/gems/ruby-2.4.0@global/bin/ruby_executable_hooks:15:in
<main>'
只需要把项目commond + R 编译一下就行了
网友评论