块结构

• 象文章分章节一样
• 注释文本也能定义各种语义区块

段落

• 简单的使用空行就好

•  def example():
      """
      这是第一段.  段落可以包含多行并可以包含有I{行内修饰}
      
      这是第二段. 段落间通过空行来区分
      """
      [...]

• 将生成为:

• 这是第一段. 段落可以包含多行并可以包含有行内修饰 这是第二段. 段落间通过空行来区分

列表

• 象MoinMoin 等等结构化文本一样,通过缩进来声明,使用 数字 或是 “-” 来引导列表项

• 可以混合

•  def example():
      """
      此为段落.
        1. 此为列表项
          - 此为子列表
          - 子列表第二项
              - 此为次层列表,同样可以继续列表下去
              - 只要有一致的缩进
  
        2. 此为列表第二项
           可以包含段落和测试引用
  
           >>> print '此为测试引用语句'
           此为测试引用语句
  
           此为第二段
      """
      [...]

• 将生成文档为:

此为段落.

1. 此为列表项
   • 此为子列表
   • 子列表第二项
     • 此为次层列表,同样可以继续列表下去
     • 只要有一致的缩进
2. 此为列表第二项
   • 可以包含段落和测试引用

     >>> print '此为测试引用语句' 此为测试引用语句 此为第二段

章节

• 使用 ReStructuredText 结构化文本的声明方式

•  def example():
      """
      此段不在任何章节中.
  
      第 1 章
      =========
        这为第 1 章中的段落
  
        章节 1.1
        -----------
        此为章节 1.1 中的段落
  
      第 2 章 
      =========
        此为第 2 章 中的段落.
      """
      [...]

• 将生成:

• 此段不在任何章节中.

第 1 章

• 这为第 1 章中的段落

章节 1.1

• 此为章节 1.1 中的段落

第 2 章

• 此为第 2 章 中的段落.

引用块

• 同样是利用ReStructuredText 的引用声明

•  def example():
      """
      使用“：：”引出引用块::
      
          原文 /
              / 引用块
  
      此为在引用块后的段落
      还是空行来区分.
      """
      [...]

• 生成的文档类似:

• 使用“：：”引出引用块:

          原文 /
              / 引用块

  此为在引用块后的段落 还是空行来区分.

行内修饰

• 简单的字体声明

•  def example():
      """
      I{B{行内修饰} 可以嵌套} 在多行内.
  
        - I{斜体}
        - B{加重}
        - C{源代码}
  
      C{my_dict={1:2, 3:4}}.
      """
      [...]

• 将生成类似文档:

• 行内修饰 可以嵌套 在多行内.

  • 斜体

  • 加重'

  • 源代码

     1     my_dict={1:2, 3:4}
  

特殊标签

URLs

•  def example():
      """
      - U{www.python.org}
      - U{http://www.python.org}
      - U{The epydoc homepage<http://
        epydoc.sourceforge.net>}
      - U{The B{I{Python}} homepage
        <www.python.org>}
      - [U{Edward Loper<mailto:edloper@
        gradient.cis.upenn.edu>}
      """
      [...]

• 对应生成文档:

• www.python.org

• http://www.python.org

• The epydoc homepage

• The Python homepage

• Edward Loper <edloper AT gradient DOT cis DOT upenn DOT edu>

交叉引用

• L{text<object>}

• 可以自动生成到其它对象的文档页面链接

• text 处是说明文字

• <object> 是具体对象的名称，类/函式/变量 名

警告

• 当然对于意外情况， epydoc 不会崩溃，只是进行警告，你可以根据提示进行修正

ZoomQuiet (2005-01-27)