Display correct method signatures in documentation

seveas · sigmavirus24 · commit eca4d0b41359 · 2012-10-28T17:56:03.000-04:00
Use an environment variable to make sphinx signal to github3 that it
wants the actual signatures of functions and doesn't care about
functionality.

github3 in turn will use mock decorators instead of real ones so
signatures do not get hidden.
diff --git a/docs/conf.py b/docs/conf.py
@@ -13,6 +13,10 @@
 
 import sys, os
 
+# This environment variable makes decorators not decorate functions, so their
+# signatures in the generated documentation are still correct
+os.environ['GENERATING_DOCUMENTATION'] = "github3"
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
diff --git a/github3/decorators.py b/github3/decorators.py
@@ -8,6 +8,7 @@
 
 from functools import wraps
 from requests.models import Response
+import os
 
 try:  # (No coverage)
     # python2
@@ -18,20 +19,7 @@
 
 
 def requires_auth(func):
-    """Decorator to note which object methods require authorization.
-
-    .. note::
-        This decorator causes the wrapped methods to lose their proper
-        signature. Please refer to the documentation for each of those.
-    """
-    #note = """.. note::
-    #The signature of this function may not appear correctly in
-    #documentation. Please adhere to the defined parameters and their
-    #types.
-    #"""
-    ## Append the above note to each function this is applied to
-    #func.__doc__ = '\n\n'.join([func.__doc__, note])
-
+    """Decorator to note which object methods require authorization."""
     @wraps(func)
     def auth_wrapper(self, *args, **kwargs):
         auth = False
@@ -53,20 +41,7 @@ def auth_wrapper(self, *args, **kwargs):
 
 def requires_basic_auth(func):
     """Decorator to note which object methods require username/password
-    authorization and won't work with token based authorization.
-
-    .. note::
-        This decorator causes the wrapped methods to lose their proper
-        signature. Please refer to the documentation for each of those.
-    """
-    #note = """.. note::
-    #The signature of this function may not appear correctly in
-    #documentation. Please adhere to the defined parameters and their
-    #types.
-    #"""
-    ## Append the above note to each function this is applied to
-    #func.__doc__ = '\n\n'.join([func.__doc__, note])
-
+    authorization and won't work with token based authorization."""
     @wraps(func)
     def auth_wrapper(self, *args, **kwargs):
         if hasattr(self, '_session') and self._session.auth:
@@ -80,3 +55,8 @@ def auth_wrapper(self, *args, **kwargs):
             r.raw = StringIO('{"message": "Requires username/password authentication"}'.encode())
             raise GitHubError(r)
     return auth_wrapper
+
+# Use mock decorators when generating documentation, so all functino signatures
+# are displayed correctly
+if os.environ.get('GENERATING_DOCUMENTATION', None) == 'github3':
+    requires_auth = requires_basic_auth = lambda x: x
