一个用于命名空间Python包和Sphinx主题的paste.script模板。
项目描述
tl.pkg - 带有Sphinx文档的命名空间Python包的模板
此包生成具有Sphinx文档和开发构建的Python包的基本文件和目录结构。它由两部分组成
一个 paste.script 模板，用于创建位于命名空间一级的Python包的样板代码，以及
一个用于配置Sphinx的Python模块，以及必要的包依赖项和一些主题。
此包与Python 2.6和2.7兼容。
用法
要使paster模板可用，请将tl.pkg安装到paster可以找到它的位置。然后运行paster
$ paster create --template tl-pkg <NAMESPACE>.<PROJECTNAME>
这将生成egg分发的样板代码，包括zc.buildout配置、Sphinx包文档的骨架以及初始化的Mercurial仓库。构建配置针对开发，因此它将在bin/test安装测试运行器，并在bin/doc安装文档构建器。
将提示一些变量，其中包括包的一行描述和一些关键字。
个性化
粘贴器需要您提供的另外三个变量用于个性化生成的包骨架。这些变量可能具有默认值，如果存在，则从名为 $HOME/.tl-pkg.cfg 的文件中读取。该文件需要遵循Python的ConfigParser理解的ini文件语法，并包含一个定义以下任何变量的部分（迄今为止任意名称）：
- 作者:
您的全名。这将在包元数据、文档以及生成的任何Python文件的版权声明中显示。
- 作者电子邮件:
您的电子邮件地址。这既出现在包元数据中，也出现在文档中。
- bitbucket用户名:
您的bitbucket用户名。这用于构造项目所属的各种URL。目前，假设项目托管在 <http://bitbucket.org/>，并且包元数据和文档中的任何URL都指向该bitbucket项目的适当页面。
包内容
这是解释生成文件和目录的目的，以及何时编辑哪些文件的建议。许多文件根本不需要编辑。
Python发行版
- setup.py:
包定义和元数据。至少在包的版本号、依赖项、入口点更改时更新此文件。
- <NAMESPACE>:
包的源代码树。不要修改命名空间包的 __init__.py 文件，以免同一命名空间中的其他包无法导入。
Mercurial仓库
- .hg:
当创建包时，Mercurial仓库已经初始化。生成的文件尚未提交。
- .hg/hgrc:
指向某些Mercurial托管中包未来URL的仓库配置（如果有的话）。它还设置了您的hg用户名。
- .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 中，而此文件的版本部分应仅取消固定此文件同一部分的buildout部分声明的开发egg包的固定。
- local.cfg:
与其它开发者无关的构建配置的本地定制。Mercurial会忽略这些定制。如果您更改此文件，从那时起请运行bin/buildout -c local.cfg。虽然一开始可能听起来有些繁琐，但将非本地配置保存在buildout.cfg中并置于版本控制之下对于测试持续集成服务器上的包等用例来说非常重要。
- versions/versions.cfg:
对于构建过程中使用的、不属于Zope工具包的任何包进行版本锁定。用于构建文档所需的tl.pkg版本被锁定为创建包文件的同一版本。在稍后升级tl.pkg时，需要更新版本锁定，同时还需要更新版本之间包模板中发生变化的任何文件。编辑此文件以锁定您包或构建过程中所需的任何egg版本。
- versions/ztk-versions-X.Y.Z.cfg:
包含在我们版本锁定中的Zope工具包的固定版本。保留此本地副本允许在没有网络访问的情况下构建构建配置。请勿编辑此文件。
通用包文档
在包的顶级目录中可以找到一些文本文件，其中包含文档的标准部分，因此期望它们位于该位置并且具有特定的名称，并且需要在不依赖Sphinx的情况下可访问。这些文件需要是有效的restructured text，因为它们在构建完整文档时会被Sphinx处理，除了版权声明和许可文本，这些内容将直接包含。
- README.txt:
概述包的目的、内容和用法，这些内容将是其PyPI页面和文档索引页面的组成部分。应始终与包内容保持一致。
- CHANGES.txt:
需要更新的变更日志，包括对包的任何更改，这些更改与包的用户相关。该文件的格式被zest.releaser所理解，并且它的当前版本（即在公共Mercurial存储库中的“最新”版本）将被指向PyPI页面和构建的包文档。
- ABOUT.txt:
有关包及其作者的提示，例如后者的电子邮件地址、包的文档、PyPI页面、问题跟踪器和源代码的URL以及当前日志。假设文档将同时发布在PyPI和<http://readthedocs.org/>上；您应该确保使用分配给您的项目的正确URL。
- COPYRIGHT.txt:
包的版权信息：包括版权所有者、版权年份以及有关使用的许可的建议，默认情况下是Zope公共许可，版本2.1。至少编辑此文件以更新年份。
- LICENSE.txt:
使用许可证的官方文本副本。除非要更换为不同的许可证，否则请勿编辑此文件。
使用Sphinx构建的完整文档
- doc:
仅与Sphinx生成的文档相关的所有内容。我们使用后缀.txt作为Sphinx输入文件。虽然存在许多关于doc目录内容的惯例，但如果您自由地修改它，包的其余部分也不会有问题；只需确保它保持有效的Sphinx输入即可。
- doc/conf.py:
Apache 配置。基本上，所有配置值都遵循约定，因此来自 tl.pkg，因此您必须保持对 tl.pkg.sphinxconf 的导入和调用。如果您只想为此包更改元数据或文档外观，则必须编辑此文件。Sphinx 生成文档的约定更新将通过升级 tl.pkg 来获取。
- doc/index.txt:
文档的首页。它包括顶级 README.txt 文件中的包概述以及指向完整文档各部分的目录。这些包括生成的 API 文档、有关包的一些元信息以及变更日志。如果您想添加顶级部分，例如，请编辑此文件。
- doc/narrative.txt:
叙事包文档的根文档。这是为了收集位于您的源树中的 Python 模块中的任何 doc-test 文件。您需要列出 toctree 指令下的文件，它们的文档名称符合 <NAMESPACE>.<PACKAGENAME>-<FILENAME> 的模式（不带 .txt 后缀）。包含注释的示例文件列表已提供。
- doc/api.txt:
生成的 API 文档的根文档。API 通过在 autosummary 指令中列出所有要文档化的模块来半自动地进行文档记录，从那时起，这将自动完成。包含注释的示例模块列表已提供。
- doc/overview.txt:
一个占位符，用于包含顶级文件 README.txt。无需编辑此文件。
- doc/about.txt:
有关包的元信息，结合顶级文件 ABOUT.txt、COPYRIGHT.txt 和 LICENSE.txt。您不需要编辑此文件。
- doc/changes.txt:
一个占位符，用于包含顶级文件 CHANGES.txt。无需编辑此文件。
- doc/requirements.pip:
列出构建文档所需的 Python eggs（不包括 Sphinx 本身）。这是为了在 http://readthedocs.org/ 上构建文档。您需要与他们白名单，才能使用由 tl.pkg 实现的约定。每当您的文档包依赖关系更改时，请编辑此文件；您不能在此使用 egg extras。
构建完整文档
生成的 buildout 配置在 bin/doc 处安装一个脚本，该脚本调用 Sphinx 来构建文档。要运行此脚本，您的当前工作目录必须是包根目录。该脚本将构建的文档放入 build/doc/（相对于包的顶级目录）。传递给 bin/doc 的选项将传递给底层的 sphinx-build 命令，但请注意，位置参数不起作用。
Sphinx 配置值
默认情况下，已启用一些 Sphinx 扩展，因此您可能希望除了核心 Sphinx 变量外还配置这些扩展
sphinx.ext.autosummary
sphinx.ext.viewcode
sphinx.ext.inheritance_diagram
sphinxcontrib.cheeseshop
sphinxcontrib.issuetracker
您可以通过在您的 conf.py 中设置相应的变量来覆盖 tl.pkg 的默认值。必须在 set_defaults 调用之后发生 tl.pkg.sphinxconf.set_defaults 的调用。
source_suffix = '.foo' import tl.pkg.sphinxconf tl.pkg.sphinxconf.set_defaults()
相反，sphinxconf 尝试使用来自 conf.py 的变量来计算值。如果指定了这些变量，则必须在调用 set_defaults 之前这样做。目前，以下变量被识别
- _year_started:
项目开始年份的可选值。默认为文档构建时的当前年份，但如果指定且与当前年份不同，则用于构建类似“2001-2012 作者”的版权声明。
- _flattr_url:
如果指定，则假定这是此项目的flattr东西的URL，并且flattr捐赠按钮将出现在完整文档菜单列的顶部。要在PyPI页面上添加flattr按钮，请取消注释ABOUT.txt中的“支持项目”项，并在其中填写URL。
- _issuetracker_offline:
如果设置为真值，则sphinxcontrib-issuetracker的bitbucket集成将被修改，以便在构建文档时不会尝试访问<http://bitbucket.org/>服务器，Sphinx运行将独立于网络访问。迄今为止，尚未处理与其他跟踪器的集成。这将禁用跟踪器集成的一些功能，但保留例如issuetracker扩展识别纯文本问题编号的能力。
最后，tl.pkg.sphinxconf模块定义了一个函数，您可以在文档需要在类似<http://readthedocs.org/>的系统上构建的系统（无法安装某些代码，如用C实现的模块）上调用该函数以注册模拟模块。
tl.pkg.sphinxconf.register_mock_modules('cairo', 'gobject', 'gtk')
已知问题
存在一个已知问题，即包含下划线的项目名称。由于tl.pkg从包的egg info推断元数据（如项目和包名称）的方式，默认情况下将下划线替换为短划线，从而导致文档构建失败。要在您的项目名称中使用下划线，请显式地在conf.py中重复名称。
project = '<NAMESPACE>.<PACKAGE_NAME_WITH_UNDERSCORES>' import tl.pkg.sphinxconf tl.pkg.sphinxconf.set_defaults()
关于tl.pkg
tl.pkg-0.1.tar.gz的散列
| 算法 | 散列摘要 | |
|---|---|---|
| SHA256 | ef8301385707fa02c44327392693612c4996da3a43f22bb1d0010323a79a6cce |
|
| MD5 | 976a5947ed92c7a809c6dab31f50b6fd |
|
| BLAKE2b-256 | 32e898feb94b7212226ee0566ce7abe4edfc81f05b195022c9df22a6f4f56733 |
