美文网首页iOS开发基础程序员iOS Developer
swift 使用Jazzy 生成代码文档

swift 使用Jazzy 生成代码文档

作者: 喔酃 | 来源:发表于2017-06-20 23:15 被阅读643次

    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. 等待
    
    1. 安装成功后cd到项目根目录下:
    $ cd path_to_project_folder
    
    1. 然后执行
    $ jazzy --min-acl internal
    
    1. 然后在终端就会看到
    $ 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<top (required)>'
    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<main>'
    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<main>'

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

    相关文章

      网友评论

      • 流年易逝_李:表示还是失败,能否说说具体操作吗?联系方式,微信1365343119或者简书,谢谢。 Could not parse compiler arguments from `xcodebuild` output.

      本文标题:swift 使用Jazzy 生成代码文档

      本文链接:https://www.haomeiwen.com/subject/tlwaqxtx.html