使用Rdoc

Posted on January 3, 2015

如何使用rdoc

  • rdoc generates documentation for all the Ruby and C source files in and below the current directory. These will be stored in a documentation tree starting in the subdirectory doc

  • rdoc --main README.rdoc TODO

  • rdoc test.rb rdoc app/models 可以只针对一个文件或者目录

  • rdoc 参数:

    –all:rdoc默认只将public方法生成doc,使用–all会将所有方法生成doc

    –fmt <xml,yaml,chm,pdf>:用指定格式生成文档

    –help:

    –inline-source:将代码显示在文档中 TODO

    –main: set the class, module, or file to appear on the index page 将“类”,“模块”或“文件”注释显示在首页(index)

    –one-file:将rdoc所有文档内容放在一个文件中

    –op<目录名>:设置输出目录的目录名

    –exclude pattern: 排除和pattern匹配的文件和目录

  • 典型输出:

    Generating Darkfish format into /home/zhonghua/code/work/campus/doc...
    
      Files:      16
    
      Classes:    16 (16 undocumented)
      Modules:     0 ( 0 undocumented)
      Constants:  20 (19 undocumented)
      Attributes:  0 ( 0 undocumented)
      Methods:    23 (21 undocumented)
    
      Total:      59 (56 undocumented)
        5.08% documented
    
      Elapsed: 0.2s
    

如何写Rdoc注释

  • 如果有类和方法不想生成doc

    eg:
    def no_doc #:nodoc:
    end
    或
    class NoDocClass #:nodoc:all
    
  • 部分注释不想生成doc

    #--
    #该行不会生成doc
    #++
    #该行会生成doc
    
  • - *:代表缩进的符号列表, 类似markdown中的无序列表

  • 有序列表同markdown

  • [说明对象]说明文字:代表描述列表,方括号内的是被描述的对象,后面是说明文字, 二者这件有换行和缩进

  • <em></em>:表示文本为斜体

  • <tt></tt>: 用html的code标签包裹

  • <b></b>:表示文本为粗体

  • http::文本为超链接

    zhongfox(http:zhongfox.github.io)

    生成的html是zhongfox(<a href="http:zhongfox.github.io">zhongfox.github.io</a>)

  • 标题

    = Level One Heading

    == Level Two Heading


Rails

  • rake doc:app generates documentation for your application in doc/app.

    包括项目中app以及lib等(TODO)下的文件

  • rake doc:guides generates Rails guides in doc/guides.

    生成的是rails官方的指南, 和项目没有半毛钱关系

    依赖redcarpet, 将gem 'redcarpet', '~> 2.1.1'加入Gemfile

  • rake doc:rails generates API documentation for Rails in doc/api.

    生成官方api文档, 版本同此项目


Rails Guides

rails主项目下的rails/guides是可以直接用于生成rails guide 风格的文档

  • rake guides:generate # Generate guides (for authors), use ONLY=foo to process just “foo.md”
  • rake guides:generate:html # Generate HTML guides
  • rake guides:generate:kindle # Generate .mobi file
  • rake guides:help # Show help
  • rake guides:validate # Validate guides, use ONLY=foo to process just “foo.html”

markdown文档格式:

主标题
===========

大纲, 将是绿色背景, 下面的连接符串为分割, 连接符要很长(TODO具体多长)

---------------------------------------------------------------------------

Section 类似于一级模块, 同样需要连接符
-------

### Sub Section 类似于二级模块, 直接用markdown的三级标题

其采用的markdownGitHub Flavored Markdown 略微区别于传统的markdown:

  • 传统2个_解释为斜体, GFM忽略(好主意)
  • url自动展示, 无需额外修饰
  • 删除线~~Mistaken text.~~
  • 除支持传统缩进代码块外, 还支持:

    Here's an example:
    
    ```
    function test() {
      console.log("notice the blank line before this function?");
    }
    ```
    

    特定语法高亮:

    ```ruby
    require 'redcarpet'
    markdown = Redcarpet.new("Hello World!")
    puts markdown.to_html
    ```
    
  • 其他: https://help.github.com/articles/github-flavored-markdown/

参考资料