python - 在 Zope 2 中使用 Sphinx 的自动文档（文档字符串问题）

Question

我想使用 Sphinx 来记录我的 Zope 2 产品，并且使用 autodoc 功能会很好，它可以从我的模块中的文档字符串中提取信息。现在在 Zope 中，不幸的是，文档字符串被用来指定一个可以通过 http-requests 访问的方法。因此，所有不应通过 http 访问的方法都没有文档字符串。

有没有办法以 Sphinx 识别但 Zope 不识别的方式编写文档字符串？

或者：有没有办法改变 Zope 文档字符串的行为？

Answer 1

我可以看到 3 种方法来做到这一点，但没有一个（无 :-) 正是你想要的，除了依靠重型机械。

1. 以 开头的方法_未发布，因此您可以这样做：

   class MyClass:
   
     def _method(self):
       "I have a docstring, but I won't be published"
       return 'done'
   

2. 您可以将角色设置为ACCESS_PRIVATE

   from AccessControl.SecurityInfo import ACCESS_PRIVATE
   
   class MyClass:
   
       myMethod__roles__ = ACCESS_PRIVATE
       def myMethod(self):
       "I look like I'm published, but I'm not"
           return 'done'
   

   在我看来，最接近您想要实现的目标，但请注意该行为与缺少文档字符串不同：如果在没有文档字符串的情况下调用该方法，则结果是NotFound异常，而在这种ACCESS_PRIVATE情况下，结果是未经授权的例外。

3. 您可以通过实现自己的来替换遍历方法（我认为）IBrowserPublisher。默认实现DefaultPublishTraverse在ZPublisher/BaseRequest.py. 然后，您必须通过复制和调整它来制作自己的，以便它使用另一个标志而不是 docstring 进行发布。