1. 块结构
- 象文章分章节一样
- 注释文本也能定义各种语义区块
1.1. 段落
- 简单的使用空行就好
def example(): """ 这是第一段. 段落可以包含多行并可以包含有I{行内修饰} 这是第二段. 段落间通过空行来区分 """ [...]- 将生成为:
这是第一段. 段落可以包含多行并可以包含有行内修饰 这是第二段. 段落间通过空行来区分
1.2. 列表
象MoinMoin 等等结构化文本一样,通过缩进来声明,使用 数字 或是 “-” 来引导列表项
- 可以混合
def example(): """ 此为段落. 1. 此为列表项 - 此为子列表 - 子列表第二项 - 此为次层列表,同样可以继续列表下去 - 只要有一致的缩进 2. 此为列表第二项 可以包含段落和测试引用 >>> print '此为测试引用语句' 此为测试引用语句 此为第二段 """ [...]- 将生成文档为:
此为段落.
- 此为列表项
- 此为子列表
- 子列表第二项
- 此为次层列表,同样可以继续列表下去
- 只要有一致的缩进
- 此为列表第二项
- 可以包含段落和测试引用
>>> print '此为测试引用语句' 此为测试引用语句 此为第二段
- 可以包含段落和测试引用
1.3. 章节
使用 ReStructuredText 结构化文本的声明方式
def example(): """ 此段不在任何章节中. 第 1 章 ========= 这为第 1 章中的段落 章节 1.1 ----------- 此为章节 1.1 中的段落 第 2 章 ========= 此为第 2 章 中的段落. """ [...]- 将生成:
- 此段不在任何章节中.
1.3.1. 第 1 章
- 这为第 1 章中的段落
1.3.1.1. 章节 1.1
- 此为章节 1.1 中的段落
1.3.2. 第 2 章
- 此为第 2 章 中的段落.
1.4. 引用块
同样是利用ReStructuredText 的引用声明
def example(): """ 使用“：：”引出引用块:: 原文 / / 引用块 此为在引用块后的段落 还是空行来区分. """ [...]- 生成的文档类似:
使用“：：”引出引用块:
原文 / / 引用块此为在引用块后的段落 还是空行来区分.
2. 行内修饰
- 简单的字体声明
def example(): """ I{B{行内修饰} 可以嵌套} 在多行内. - I{斜体} - B{加重} - C{源代码} C{my_dict={1:2, 3:4}}. """ [...]- 将生成类似文档:
行内修饰 可以嵌套 在多行内.
斜体
加重'
源代码
1 my_dict={1:2, 3:4}
2.1. 特殊标签
2.1.1. 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>} """ [...]- 对应生成文档:
- Edward Loper <edloper AT gradient DOT cis DOT upenn DOT edu>
2.1.2. 交叉引用
L{text<object>}
- 可以自动生成到其它对象的文档页面链接
text 处是说明文字
<object> 是具体对象的名称，类/函式/变量 名
3. 警告
- 当然对于意外情况， epydoc 不会崩溃，只是进行警告，你可以根据提示进行修正
ZoomQuiet (2005-01-27)