Using Sphinx's autodoc with Zope 2 (docstring issue)

Question

I'd like to use Sphinx to document my Zope 2 Product and it would be nice to also use the autodoc feature, which pulls informations out of docstrings in my modules. Now in Zope the docstrings are unfortunately used to designate a method as accessible through http-requests. So all methods that should not be accessible through http have no docstring.

Is there a way to write the docstring in a way that it is recognized by Sphinx but not by Zope?

Or: Is there a way to change the Zope docstring behaviour?

Answer 1

I can see 3 ways to do it, but none (None :-) is exactly what you want, except on relying on heavy machinery.

1. methods starting with _ aren't published, so it might be ok for you to do it:

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

2. you can set role to 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'
   

   In my opinion, the closest to what you want to achieve, but be aware that the behaviour is different from a missing docstring: if the method is called while it has no docstring, the result is a NotFound exception, while in the ACCESS_PRIVATE case, the result is an Unauthorized exception.

3. You can replace the traversal method (I think) by implementing your own IBrowserPublisher. The default implementation is DefaultPublishTraverse in ZPublisher/BaseRequest.py. You then have to make your own by copying it and tweak it so that it uses another flag than docstring for publication.