0

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Georg Pfolz
  • 1,416
  • 2
  • 12
  • 12

1 Answers1

2

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.

Victor von Cacahuete
  • 194
  • 6
  • You're right, the second way is what I was looking for. The Unauthorized exception is fine for me :) Thank you kindly! – Georg Pfolz Sep 19 '13 at 20:46
  • I was missing one point: If I go with the second way I render all methods in the class unpublishable. Is there a way to mark some methods as publishable through the web? – Georg Pfolz Sep 20 '13 at 18:11
  • No, no, it's on a method-by-method basis. May be calling it "method" in my example was a poor choice for the sake of explanation, so I renamed it "myMethod". As you can see, the roles apply only to the function "myMethod". – Victor von Cacahuete Sep 20 '13 at 19:21