gocept.package 3.1

Python发行版

setup.py:

包定义和元数据。每次包的版本号、依赖项或入口点更改时，至少更新此文件。

src:

包的源代码树。不要修改命名空间包的__init__.py文件，否则同一命名空间中的其他包无法导入。

Mercurial仓库

.hg:

当创建包时，Mercurial仓库已经初始化。生成的文件尚未提交。

.hg/hgrc:

指向gocept公共Mercurial托管中包未来URL的仓库配置。如果您需要为该包设置不同于默认的作者，请编辑此文件（或使用hg persona）。

.hgignore:

Mercurial应忽略的文件和目录。这包括本地配置以及buildout、文档构建或包发布预期生成的文件。它不包括Python生成的文件（如*.pyc）、distribute（*.egg-info）或其他更通用的工具（如您的编辑器），这些工具不是特定于此项目的。这些模式应在您的默认Mercurial忽略列表中。

开发buildout

bootstrap.py:

创建bin/buildout脚本。使用buildout应使用的相同Python解释器运行此脚本。无需编辑此文件。

buildout.cfg:

为包创建测试运行器和文档构建器的有效buildout配置。包本身作为开发egg包含在内，buildout配置为仅使用任何其他包的固定版本。编辑此文件以配置包的官方开发buildout，但将本地自定义放在local.cfg中。版本固定放在versions/versions.cfg中，而此文件的版本部分应仅撤销此文件构建部分声明的开发egg的固定。

local.cfg:

对buildout配置的本地自定义，对其他开发者没有兴趣。这是被Mercurial忽略的。如果您更改此文件，从那时起请始终从bin/buildout -c local.cfg运行。虽然一开始这可能听起来很麻烦，但保持非本地配置在buildout.cfg下并进行版本控制对于测试包在持续集成服务器上的使用案例等重要。

versions/versions.cfg:

为构建过程中使用的、不属于Zope工具包的任何包进行版本锁定。用于构建文档所需的gocept.package版本被锁定到创建包文件相同的版本。在稍后升级gocept.package时，需要更新版本锁定，以及版本之间包模板中任何发生变化的文件。编辑此文件以锁定您的包或构建配置所需的任何eggs版本。

versions/ztk-versions-X.Y.Z.cfg:

包含在我们的版本锁定中的Zope工具包的固定版本。保留此本地副本可以在没有网络访问的情况下构建构建配置。不要编辑此文件。

杂项

.coveragerc:

为coverage.py配置。

通用包文档

在包的顶级目录中可以找到一些文本文件，它们包含标准文档片段，因此应位于该位置和特定名称下，并且需要独立于Sphinx可访问。这些文件需要是有效的reStructuredText，因为Sphinx在构建完整文档时会处理它们，除了版权声明和许可文本外，这些文本将直接包含。

README.rst:

对包的目的、内容和用法的概述，这将包含在它的PyPI页面上以及文档的索引页面上。应始终与包内容保持最新。

CHANGES.rst:

需要更新的变更日志，其中包含对包的任何更改，这些更改与包的用户相关。该文件的格式由zest.releaser理解，并指向当前版本（即公共Mercurial存储库中的“tip”版本），它将从PyPI页面上指向以及构建的包文档。

HACKING.rst:

有关包及其作者的某些提示，例如后者的电子邮件地址以及包的文档、PyPI页面、问题跟踪器和源代码的URL以及当前日志。

COPYRIGHT.txt:

关于包的版权信息：包括版权所有者、版权年份以及有关所使用许可的一些建议，默认情况下为Zope公共许可2.1版。至少编辑此文件以更新年份。

LICENSE.txt:

所使用许可的官方文本副本。除非需要将其替换为不同的许可，否则不要编辑此文件。

使用Sphinx构建的完整文档

doc:

仅与Sphinx生成的文档相关的所有内容。我们使用后缀.txt作为Sphinx输入文件。虽然存在许多关于doc目录内容的规定，但如果您自由修改它，则不会对包的其余部分造成任何坏处；只需确保它保持有效的Sphinx输入。

doc/conf.py:

Sphinx配置。基本上所有配置值都遵循我们的约定，因此从gocept.package导入，因此您必须保持对gocept.package.sphinxconf的导入和调用完整。如果您想更改有关此包的元数据或文档外观的任何内容，您将需要编辑此文件。对我们关于Sphinx生成的文档的约定的更新将通过更新gocept.package来获取。

doc/index.txt:

文档的首页。它包括顶级README.rst文件中的包概述以及指向完整文档各部分的目录。这包括生成的API文档、有关包的一些元信息以及变更日志。如果您想添加如叙事包描述之类的顶级部分，请编辑此文件。

doc/api.txt:

生成的API文档的根文档。API文档是半自动化的，您需要在文件中的autosummary指令下列出所有要文档化的模块，从那时起会自动进行。已包含一个注释示例模块列表。

doc/about.txt:

关于包的元信息，结合顶级文件HACKING.rst、COPYRIGHT.txt和LICENSE.txt。您不需要编辑此文件。

doc/changes.txt:

一个占位符，用于包含顶级文件CHANGES.rst。无需编辑此文件。