更多与Zope兼容的Sphinx自动文档器。
项目描述
waeup.sphinx.autodoc 是一个 Sphinx 扩展，用于自动文档化特定于 Zope3 和 Grok 的组件/类。
此项目处于早期阶段。请谨慎使用。
目前可用的功能
在自动文档化时，忽略名称中包含点的组件。这可以大大减少在使用 Sphinx 与 Grok 项目时获得的 AttributeErrors（否则无法处理）的数量。
新的 grokindexes 自动文档器记录 grok.Indexes 声明。
安装
本Python包可以通过pip进行安装。
$ pip install waeup.sphinx.autodoc
通常情况下，您会与Zope3或Grok项目一起安装waeup.sphinx.autodoc。它必须以某种方式安装，以便Sphinx可以找到该包。具体方式取决于您的项目。对于大多数项目，只需将waeup.sphinx.autodoc添加到您的setup.py文件中的install_requires字典即可。
使用
安装完成后，您可以在本地Sphinx源代码的conf.py中激活该包。
# conf.py
#
# ...
#
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'waeup.sphinx.autodoc',
# ...
]
#
# ...
#
请注意，您还必须激活Sphinx自动提供的sphinx.ext.autodoc。
waeup.sphinx.autodoc提供了新的配置变量和新指令。
ignore_dot_named_members
此配置值可以在项目的conf.py中设置
# conf.py # ... ignore_dot_named_members = True # ...
默认设置为True。避免Sphinx在点号中的成员名称上阻塞。
如果设置为True，我们将跳过所有名称中包含点的成员，例如grokcore.component.directive这样的成员。这类成员名称在例如grok中广泛使用。
对于Sphinx来说，这是一个问题，因为它假设名称中的点表示父对象的成员对象。结果导致了大量的AttributeErrors。
grokindexes
此指令渲染一个grok.Indexes实例。由于grok.Indexes通常是某个类的实例，而不是类本身，因此任何grok.Indexes 'class' 也不会被Sphinx视为类。
使用waeup.sphinx.autodoc，您可以使用新的grokindexes指令在代码中描述一个grok.Indexes实例
.. grokindexes:: mymod.MyCatalog
Description of MyCatalog
还可以自动扫描grok.Indexes实例。为此，您可以使用autogrokindexes
.. autogrokindexes:: mymod.MyCatalog
当然，在这种情况下，mymod.MyCatalog必须在Sphinx运行期间可导入。
开发者安装
对于那些想修改waeup.sphinx.autodoc包本身的人来说。
开发者可以从github上克隆一个副本
$ git clone https://github.com/WAeUP/waeup.sphinx.autodoc.git
我们建议首先创建并激活一个virtualenv
$ cd waeup.sphinx.autodoc $ virtualenv -p /usr/bin/python2.7 py27 $ source py27/bin/activate (py27) $
我们支持Python版本2.6和2.7。
现在您可以创建开发环境
(py27) $ python setup.py dev
这将获取测试包（py.test）和其他运行测试所需的包。由于我们需要grok和其他依赖于大量其他包的包，不幸的是，将下载和安装大量的包。
如果下载中断，请保持冷静，通过重试来继续。
运行测试
完成此操作后，您应该能够运行测试
(py27) $ py.test
如果您安装了不同的Python版本，您可以使用tox来对这些版本运行测试
(py27) $ pip install tox # only once (py27) $ tox
应该在所有官方支持的Python版本上运行测试
(py27) $ tox -e py26
将使用特定的Python版本（此处：Python 2.6）运行测试
许可协议
此Python包根据GPL v3+许可。
版权所有(C) 2015 Uli Fouquet和WAeUP Germany。
