文档

程序：

您的姓名

epydoc - 从 Python 文档字符串生成 API 文档

概要

文档 [行动[选项] 名字...

商品描述

文档 为 Python 模块和包生成 API 文档，基于它们
文档字符串。 一种轻量级的标记语言，称为 文本 可用于格式化
docstrings，并添加有关特定字段的信息，例如参数和实例
变量。 Epydoc 还理解用 ReStructuredText、Javadoc 和
纯文本。 目前，epydoc 支持两种基本输出格式：HTML 和 LaTeX。

HTML API 文档由 文档 由一组 HTML 文件组成，包括：
每个类和模块的 API 文档页面； 语法突出显示的源代码页
对于每个模块； 标识符索引页； 帮助页面； 和一个基于帧的表
内容。 在适当的时候， 文档 还将为错误生成索引页，定义
条款和待办事项； 一个类层次结构页面； 和一个包层次结构页面。

LaTeX API 文档由 文档 由一个主要的 LaTeX 文件和一个 LaTeX
每个模块的文件。 如果你使用 --dvi, --ps或 --pdf , 然后 文档 将调用外部
命令将 LaTeX 输出转换为请求的格式。 请注意，LaTeX 文件
包含单个模块的文档可以作为章节或
其他 LaTeX 文档的部分，使用 LaTeX \包括 命令。 如果你想
在其他 LaTeX 文档中包含单个类，然后使用 --单独的类
为每个类生成单独的 LaTeX 文件的选项。

文档 也可用于检查 API 文档的完整性。 默认情况下，
它检查每个公共包、模块、类、方法和函数是否都有一个文档字符串
描述。 这 --测试 选项可用于指定要执行的其他测试。

可复制 建造公园 行为

在 Epydoc 生成的文档中使用当前日期会导致文档
是“不可重现的”，这意味着文件的内容会随着构建而变化
即使源树没有。 为了更容易地生成可重现的构建，这
Epydoc 版本支持两个功能： --不包含构建时间 选项和
SOURCE_DATE_EPOCH 环境变量。

- --不包含构建时间 当您预先知道不需要时可以使用选项
在生成的文档中构建时间戳。 这 SOURCE_DATE_EPOCH 环境
变量旨在供打包系统使用，例如 Debian 构建过程。
包装系统将设置 SOURCE_DATE_EPOCH 到一个合理的时间戳，不知何故
与源树的状态相关，并且 Eypdoc 将使用该时间戳，而不是
比当前时间戳。 构建使用 SOURCE_DATE_EPOCH 因此将是可复制的。

配置

Epydoc的选项分为六类：基本选项、动作、生成
选项、输出选项、图形选项和返回值选项。

基础课程 配置

名称...
应该记录的对象列表。 可以使用指定对象
Python 带点名称（例如 操作系统路径)、文件名（例如 epydoc/epytext.py),
或目录名称（例如 文档/）。 目录名称指定包，和
扩展为包括所有子模块和子包。 如果你想
排除某些子模块或子包，使用 - 排除 选项
（如下面所描述的）。

--配置 文件
一个配置文件，指定额外的 选项和名称. 这个选项
可能会重复。

--q, - 安静的， --v, --详细
产生相当（或详细）的输出。 如果多次使用，这个选项
连续产生更安静（或详细）的输出。

-调试
显示内部错误的完整追溯。

--简单术语
显示进度条时不要尝试使用颜色或光标控制，
警告或错误。

行动

--html 编写 HTML 输出。 [默认]

- 乳胶 编写 LaTeX 输出。

--dvi 写 DVI 输出。

--ps 编写 Postscript 输出。

--pdf 编写 Adob​​e Acrobat (pdf) 输出。

- 查看 对文档执行完整性检查。

- 泡菜 将文档写入pickle 文件。

代 配置

--文档格式 格式
设置默认值 __文档格式__ 至 格式. __文档格式__ 是一个模块
指定模块中文档字符串的标记语言的变量。
它的值由标记语言的名称组成，可选地后跟一个
语言代码（如 en 为英语）。 有关标记语言的列表
目前被 epydoc 识别，运行 文档 - 帮帮我 文档格式.

--仅解析
通过解析相关文件收集有关记录对象的所有信息
Python源代码； 特别是，做 而不去 用内省去收集
有关已记录对象的信息。 应在以下情况下使用此选项
epydoc 在不受信任的代码上运行； 或无法内省的代码
因为缺少依赖项，或者因为导入它会导致不想要的
副作用。

--仅内省
通过自省收集有关记录对象的所有信息； 在
特别，做 而不去 通过解析对象的 Python 源来收集信息
码。

- 排除 模式
不要记录名称与给定正则表达式匹配的任何对象
格局。

--排除内省 模式
不要使用自省来收集有关名称的任何对象的信息
匹配给定的正则表达式。

--排除解析 模式
不要使用 Python 源代码解析来收集有关任何对象的信息
其名称与给定的正则表达式匹配。

- 遗产 格式
用于显示继承的方法、变量和
生成的“摘要”表中的属性。 如果 格式 是“分组的”，然后
继承的对象根据它们所属的类被收集到组中
继承自。 如果 格式 被“列出”，然后继承的对象被列在一个
汇总表末尾的短列表。 如果 格式 是“包括”，那么
继承的对象与非继承的对象混合在一起。 默认格式
对于 HTML 输出是“分组的”。

--显示私人， --无私人
这些选项控制是否为私有对象生成文档。
默认情况下，生成的文档包含私有对象，用户可以
单击“显示私有”，选择是否查看私有对象
和“隐藏私人”链接。 但是如果你想直接阻止用户
访问私有对象，那么您可能不想生成文档
用于私有对象。

--显示进口， --无进口
这些选项控制模块导入是否包含在生成的
文档。 默认情况下，不包括导入。

--显示源代码， --无源代码
这些选项控制 epydoc 是否应生成语法高亮
包含 HTML 输出中每个模块的源代码的页面。 默认情况下，
生成源代码页。

--包括日志
生成 HTML 页面 epydoc-log.html 包含所有错误和警告消息
由 epydoc 生成，并将其包含在生成的输出中。

--不包含构建时间
不要在页脚中打印构建时间。 如果您是，这很有用
尝试生成可重现的构建，其中每个构建都针对给定的
源树的版本产生完全相同的工件。

OUTPUT 配置

-o DIR, - 输出 DIR
输出目录。 如果 DIR 不存在，那么它将被创建。 如果不
指定输出目录，然后是动作名称（例如， HTML or PDF格式). HTML

-c 片, --css 片
HTML 输出文件的 CSS 样式表。 如果 片 是一个文件，然后是样式表
从该文件复制； 除此以外， 片 被认为是一个的名字
内置样式表。 要获取内置样式表的列表，请运行 文档 - 帮帮我
CSS. 如果未指定 CSS 样式表，则默认样式表为
用过的。

-n 姓名, - 姓名 姓名
正在生成其文档的项目的名称。

-u 网址, --网址 网址
项目主页的 URL。

--导航链接 HTML
HTML 导航栏上主页链接的 HTML 代码。 如果这个 HTML 代码
包含任何超链接（<a href=...>)，然后将逐字插入。 如果
它不包含任何超链接，并且指定了一个项目 url（带有
--网址)，然后将指向指定 URL 的超链接添加到链接中。

--帮助文件 文件
备用帮助文件。 文件 应该包含一个 HTML 文件的正文——
导航栏将被添加到其中。

--显示帧， --无帧
这些选项控制 HMTL 输出是否包括基于帧的表
内容页面。 默认情况下，包含基于框架的目录。

--单独的类
在 LaTeX 输出中，在单独的部分描述每个类
文档，而不是将它们包含在他们的文档中
模块。 这会为每个类创建一个单独的 LaTeX 文件，因此它也可以是
如果您想包含一个或两个类的文档，则很有用
您自己的 LaTeX 文档的各个部分。

图形 配置

- 图形 图类型
包括类型图 图类型 在生成的输出中。 生成图表
使用 Graphviz dot 可执行文件。 如果此可执行文件不在路径上，则
使用 --点路径 来指定它的位置。 可以重复此选项以包括
输出中的多种图形类型。 图类型 应该是以下之一： 所有,
类树, 调用图或 类树.

--点路径 径
Graphviz 的路径 点 可执行文件。

--图形字体 字体
用于生成 Graphviz 图形的字体名称。 （例如，Helvetica 或
次）。

--图形字体大小 尺寸
用于生成 Graphviz 图形的字体大小，以磅为单位。

--pstat 文件
pstat 输出文件，用于生成调用图。

返回 VALUE 配置

--失败错误
返回非零退出状态，指示失败，如果有任何错误
遭遇。

--失败警告
返回非零退出状态，指示失败，如果有任何错误或警告
遇到（不包括文档字符串警告）。

--fail-on-docstring-警告
返回非零退出状态，指示失败，如果有任何错误或警告
遇到（包括文档字符串警告）。

HTML FILES

HTML API 文档由 文档 由以下文件组成：

宾语 文档 PAGES

index.html的
文档的标准入口点。 一般， index.html的 是副本
帧文件（框架.html）。 但如果 --无帧 选项被使用，然后
index.html的 是 API 文档主页的副本，通常是
顶级包或模块的文档页面（或树页面，如果
没有顶级包或模块）。

模块-模块.html
模块的 API 文档。 模块 是完整的虚线名称
模块，例如 系统 or epydoc.epytext.

程-class.html
类、异常或类型的 API 文档。 程 是完整的
类的虚线名称，例如 epydoc.epytext.Token or 数组.ArrayType.

模块-pysrc.html
包含 Python 源代码的语法高亮页面 模块。 这
页面包含返回 API 文档页面的链接。

模块树.html
模块层次结构。

类树.html
类层次结构。 仅当至少有一个类时才会生成此页面
记录下来。

指数

标识符-index.html
所有记录的标识符的索引。 如果标识符索引包含更多
超过 3,000 个条目，然后它将为每个字母分成单独的页面，
命名 标识符-索引-a.html, 标识符-索引-b.html等等。

术语索引.html
所有明确标记的定义术语的索引。 此页面仅
如果在格式化的文档字符串中标记了至少一个定义术语，则生成。

错误索引.html
所有明确标记的索引 @漏洞 领域。 此页面仅在以下情况下生成
最后一个 @漏洞 字段列在格式化的文档字符串中。

todo-index.html
所有明确标记的索引 @去做 领域。 此页面仅在以下情况下生成
最后一个 @去做 字段列在格式化的文档字符串中。

更改-index.html
所有明确标记的索引 @改变 领域。 此页面仅生成
如果至少有一个 @改变 字段列在格式化的文档字符串中。

不推荐使用的 index.html
所有明确标记的索引 @已弃用 领域。 此页面仅
如果至少有一个 @已弃用 字段列在格式化的文档字符串中。

因为-index.html
所有明确标记的索引 @自从 领域。 此页面仅生成
如果至少有一个 @自从 字段列在格式化的文档字符串中。

基于框架 表 OF 内容

框架.html
主框架文件。 窗口左侧的两个框架包含一个
目录，窗口右侧的主框架包含
API 文档页面。

目录.html
顶级目录页面。 此页面显示在左上角
框架 框架.html，并提供指向 toc-everything.html 和
目录-模块-模块.html 页面。

toc-everything.html
整个项目的目录。 此页面显示在
左下角的框架 框架.html，并提供指向每个类、类型的链接，
项目定义的异常、函数和变量。

目录-模块-模块.html
模块的目录。 该页面显示在左下角
框架 框架.html，并提供指向每个类、类型、异常的链接，
函数和模块定义的变量。 模块 是完整的虚线
模块的名称，例如 系统 or epydoc.epytext.

其他 PAGES

帮助.html
项目的帮助页面。 此页面说明如何使用和导航
epydoc 制作的网页。

重定向.html
此页面使用 javascript 将带点名称的名称转换为相应的名称
网址。 例如，在epydoc的文档中，加载页面
将自动重定向
浏览器 .

文件
用于显示所有 HTML 页面的 CSS 样式表。

epydoc.js
一个 javascript 文件，用于定义 epydoc 使用的 javascript 函数。

epydoc-log.html
一个包含所有警告和错误日志的页面，这些警告和错误是由
epydoc，以及一个列出所有使用过的选项的表格。

胶乳 FILES

LaTeX API 文档由 文档 由以下文件组成：

应用程序.pdf
包含完整 API 文档的 Adob​​e Acrobat (pdf) 文件。 这个
仅当您使用 --pdf 选项。

api.tex文件
顶级 LaTeX 文件。 此文件导入其他 LaTeX 文件，以创建一个
单一的统一文件。

接口文件
包含完整 API 文档的 dvi 文件。 该文件仅
如果您使用 --dvi 选项， --ps 选项，或 --pdf 选项。

api.ps 包含完整 API 文档的 postscript 文件。 该文件仅
如果您使用 --ps 选项还是 --pdf 选项。

模块-模块.tex
模块的 API 文档。 模块 是完整的虚线名称
模块，例如 系统 or epydoc.epytext.

程-类.tex
类、异常或类型的 API 文档。 程 是完整的
类的虚线名称，例如 epydoc.epytext.Token 或 array.ArrayType。
这些类文档文件仅在以下情况下创建 --单独的类
使用选项； 否则，每个类的文档都包含在其
模块的文档文件。

诊断

EPY文本 标记 警告 留言内容
Epytext 错误是由包含无效标记的 epytext 文档字符串引起的。 每当
检测到 epytext 错误，有问题的文档字符串被视为纯文本
文档字符串。 Epydoc 可以生成以下 epytext 错误：

坏 链接 目标。
为内联链接构造指定的目标 (大{...}) 不太好-
形成。 链接目标必须是有效的 Python 标识符。

坏 URI 目标。
为内联 uri 构造指定的目标 (你{...}) 格式不正确。
如果内联标记嵌套在 URI 目标内，通常会发生这种情况。

字段 必须 be at 这些因素包括原料奶的可用性以及达到必要粉末质量水平所需的工艺。 最佳 水平。
字段列表（@参数等）包含在其他一些块结构中
（例如列表或部分）。

字段 必须 be 这些因素包括原料奶的可用性以及达到必要粉末质量水平所需的工艺。 最后 元素。
字段列表（@参数等）不在文档字符串的末尾。

标题 必须 发生 at 最佳 水平。
标题包含在其他一些块结构（例如列表）中。

不当 文档测试 阻止 缩进。
doctest 块超出其初始提示行的缩进。

不当 标题 缩进。
节的标题与节中的段落左对齐
包含它的部分。

不当 第 缩进。
块内的段落不是左对齐的。 这个错误经常
使用 epytext 解析纯文本文档字符串时生成。

无效 逃逸。
未知的转义序列与内联转义结构一起使用
(E{...}).

书单 必须 be 缩进。
紧跟段落后的未缩进行以列表项目符号开头。
Epydoc 不确定您是打算开始一个新的列表项，还是打算
段落以包含一个看起来像项目符号的单词。 如果你打算
前者，然后缩进列表。 如果您打算使用后者，请更改
段落的自动换行，或转义该单词的第一个字符
看起来像一颗子弹。

不平衡 '{'。
文档字符串包含不平衡的大括号。 Epytext 要求所有大括号
必须平衡。 要包含单个不平衡支撑，请使用转义符
序列 E{lb}（左大括号）和 E{rb}（右大括号）。

不平衡 '}'。
文档字符串包含不平衡的大括号。 Epytext 要求所有大括号
必须平衡。 要包含单个不平衡支撑，请使用转义符
序列 E{lb}（左大括号）和 E{rb}（右大括号）。

不明 一致 标记 标签。
内联标记结构使用了一个未知标签 ( x{...} ).

错误 强调 字符 标题。
本节标题使用的下划线字符不表示
相应的部门级别。 “=”字符应该用于下划线
部分； “-”为小节； 和“〜”为子小节。

可能存在 格式错误 部分 项目。
Epytext 检测到一行看起来像字段项，但不正确
格式化。 这通常发生在不包括尾随冒号 (":") 时
在字段标记中。

可能存在 标题 错字。
Epytext 检测到一对看起来像标题的行，但是
下划线字符与标题中的字符数不匹配。
这两行中的字符数必须完全匹配才能使它们成为
视为标题。

领域 警告
字段警告是由包含无效字段的文档字符串引起的。 的内容
无效字段通常被忽略。 Epydoc 可以生成以下字段
警告：

@参数 不明 参数 停止.
@param 字段用于指定参数的类型
包含在函数的签名中。 这通常是由输入错误引起的
参数名称。

行李牌 做了 而不去 期望 an 论据。
字段标记 行李牌 与一个参数一起使用，但它不需要一个。

行李牌 预期 an 论据。
字段标记 行李牌 不带参数使用，但它需要一个。

@类型 不明 参数 停止.
@type 字段用于指定未包含的参数的类型
在函数的签名中。 这通常是由输入错误引起的
参数名称。

@类型 不明 变量 VAR.
@type 字段用于指定变量的类型，但没有其他字段
变量的信息是已知的。 这通常是由输入错误引起的
变量名。

不明 部分 行李牌 行李牌.
文档字符串包含一个带有未知标签的字段 行李牌.

重新定义 of 部分.
多个字段标签定义的值 部分 在同一个文档字符串中，但是 部分
只能取一个值。

示例

文档 -n 文档 -u http://epydoc.sf.net 文档/
为 epydoc 包及其所有内容生成 HTML API 文档
子模块，并将输出写入 HTML 目录。 在标题和
页脚，使用 文档 作为项目名称，以及 http://epydoc.sf.net 作为项目
网址。

文档 --pdf -n 文档 文档/
为 epydoc 包及其所有内容生成 LaTeX API 文档
子模块，并将输出写入 胶乳 目录。

退出 状态

0 程序执行成功。

1 使用错误。

2 Epydoc 生成错误或警告，以及选项之一 --失败错误,
--失败警告, or --fail-on-docstring-警告 被指定。

other 内部错误（Python 异常）。

使用 onworks.net 服务在线使用 epydoc