对本文档的贡献
本文档的参考部分描述了PyQt5的每个元素应用程序编程接口。它基于原始Qt文档,其中当然包含许多对C++的引用。其目的是,随着时间的推移将进行更新,以将所有C++习惯用法替换为Python等效用法。然而,考虑到API的大小,这项任务不太可能完整。
用于创建文档的系统设计得很简单让用户贡献补丁,将其从C++转换为Python时间。这样做是为了确保文档可以更新了PyQt5和Qt的新版本,没有任何损失用户控制的修改。
文档本身被编写为reStructuredText,并使用狮身人面像。
文档有自己的公共Mercurial存储库在这里。存储库可以使用以下命令进行克隆:
汞 克隆 https协议以下为://网址:www。河岸计算。通用域名格式/汞/PyQt5文档
最新版本将始终位于违约
分支。
存储库结构
这个文档
目录包含手写的概述文档。
这个文档/api
目录包含API的结构框架文档。它是从PyQt5自动生成的.啜饮
文件和随着PyQt5的每个新版本更新。它们包括所有API的元素,包括方法参数和类型,但不包含对这些元素的任何描述。不得手动修改。
这个描述
目录包含的每个单独元素的文件PyQt5 API——甚至包括单个枚举成员。除此之外,文件包含描述API元素的reStructuredText和:状态:
描述描述状态的字段。就是这个:状态:
字段确保任何用户贡献的修改都不会随后被覆盖。描述文件最初是在PyQt5的新版本向API引入了新元素。这些描述尚未修改的文件将被的每个新版本覆盖数量。
这个图像
目录包含中引用的图像描述文件。最初,它们是从Qt文档中复制的可能会被更多以Python为中心的替代品所取代。
这个片段
目录包含中引用的代码段描述文件。最初它们是从Qt文档中复制的,但每一行C++代码都变成了Python注释。
这个狮身人面像
目录包含Sphinx扩展和实现的主题文档系统。
这个sip2rst.py公司
每当PyQt5的新版本发布时,都会运行该脚本。它更新文档/api
和描述
目录。
这个webxml2rst.py网站
每当Qt发布新版本时,脚本都会运行。它更新描述
,图像
和片段
目录。
注释
用于描述文件的命名约定要求存储库被克隆到区分大小写的文件系统。
描述文件
对文档的大部分贡献将是描述文件的补丁。每个模块的描述文件都放在特定于模块的文件中的子目录描述
。派生描述文件的名称从所描述的API元素的完全限定名,类型标记,可选的唯一标识符,以及.rst(第一个)
扩展。
例如Q对象班是descriptions/QtCore/QObject-c.rst
。这里是类型标签c(c)
表示类。完整的类型标记集如下表所示。
一 |
属性 |
c(c) |
一节课 |
e(电子) |
枚举 |
(f) |
函数或方法 |
米 |
一个模块 |
秒 |
信号 |
v(v) |
枚举成员 |
函数、方法或信号可能具有重载。每个过载在中进行了描述一个单独的文件。在这些情况下,每个文件的名称还包括一个唯一的数字识别器。你必须看看:实际大小:
中的字段描述文件,以确定该文件描述的重载。
除了reST描述本身,描述文件的唯一部分应该修改的是:状态:
字段。这个的可能值字段如下所述。
- 待办事项
描述是从Qt的最新版本中提取的(如果是,则为存根未提取任何内容),且随后未进行修改。一定会的在Qt的下一版本发布时被替换。
- 完成
描述已修改,不会被下一个覆盖发布Qt。
- 回顾
描述已修改。然而自修改后,Qt文件本身已更新。因此,应审查Qt文件的更改,以确定是否应对描述进行相应的更改。
从上面可以看出,对描述文件的任何贡献更改应设置:状态:
字段到完成
。
不得修改描述文件中的任何其他字段。
描述本身可以使用任何正常的Sphinx和docutils域,指令和角色。唯一的例外是,所有交叉引用PyQt5 API的元素应使用:sip:ref
角色。例如对的引用Q对象类应指定为:sip:ref:`~PyQt5.Qt核心。Q对象`
。
贡献的修补程序
用户提供的修补程序可以覆盖以下任何一种:
描述
文档
图像
片段
狮身人面像/河岸/静态/河岸.css
。
使用汞 差异
命令。修补程序应通过电子邮件发送到支持@河岸计算。通用域名格式。