prompt: We are currently solving the following issue within our repository. Here is the issue text:
  --- BEGIN ISSUE ---
  Top-Level Python API methods don't have docstrings rendered in docs
  # Description
  
  The top level Python API methods pages on the docs website doesn't contain any of the rendered docstrings. For example, the `pyhf.set_backend()` API has examples (and it rather important for new users)
  
  https://github.com/scikit-hep/pyhf/blob/e55eea408d7c28e3109338de96252119ac63f87a/src/pyhf/__init__.py#L42-L52
  
  but the docs website doesn't show any of this
  
  ![not_rendered](https://user-images.githubusercontent.com/5142394/88368070-def79000-cd52-11ea-9f0e-5acbb4d45c6b.png)
  
  
  # Expected Behavior
  
  Have the docstrings be rendered in the docs 
  
  # Actual Behavior
  
  c.f. above
  
  # Steps to Reproduce
  
  Build the docs
  
  # Checklist
  
  - [x] Run `git fetch` to get the most up to date version of `master`
  - [x] Searched through existing Issues to confirm this is not a duplicate issue
  - [x] Filled out the Description, Expected Behavior, Actual Behavior, and Steps to Reproduce sections above or have edited/removed them in a way that fully describes the issue
  
  
  --- END ISSUE ---
  
  Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
  --- BEGIN FILES ---
  Path: `src/pyhf/events.py`
  Content:
  ```
  1 import weakref
  2 
  3 __events = {}
  4 __disabled_events = set([])
  5 
  6 
  7 def noop(*args, **kwargs):
  8     pass
  9 
  10 
  11 class WeakList(list):
  12     def append(self, item):
  13         list.append(self, weakref.WeakMethod(item, self.remove))
  14 
  15 
  16 class Callables(WeakList):
  17     def __call__(self, *args, **kwargs):
  18         for func in self:
  19             # weakref: needs to be de-ref'd first before calling
  20             func()(*args, **kwargs)
  21 
  22     def __repr__(self):
  23         return "Callables(%s)" % list.__repr__(self)
  24 
  25 
  26 def subscribe(event):
  27     """
  28     This is meant to be used as a decorator.
  29     """
  30     # Example:
  31     #
  32     # >>> @pyhf.events.subscribe('myevent')
  33     # ... def test(a,b):
  34     # ...   print a+b
  35     # ...
  36     # >>> pyhf.events.trigger_myevent(1,2)
  37     # 3
  38     global __events
  39 
  40     def __decorator(func):
  41         __events.setdefault(event, Callables()).append(func)
  42         return func
  43 
  44     return __decorator
  45 
  46 
  47 def register(event):
  48     """
  49     This is meant to be used as a decorator to register a function for triggering events.
  50 
  51     This creates two events: "<event_name>::before" and "<event_name>::after"
  52     """
  53     # Examples:
  54     #
  55     # >>> @pyhf.events.register('test_func')
  56     # ... def test(a,b):
  57     # ...   print a+b
  58     # ...
  59     # >>> @pyhf.events.subscribe('test_func::before')
  60     # ... def precall():
  61     # ...   print 'before call'
  62     # ...
  63     # >>> @pyhf.events.subscribe('test_func::after')
  64     # ... def postcall():
  65     # ...   print 'after call'
  66     # ...
  67     # >>> test(1,2)
  68     # "before call"
  69     # 3
  70     # "after call"
  71     # >>>
  72 
  73     def _register(func):
  74         def register_wrapper(*args, **kwargs):
  75             trigger("{0:s}::before".format(event))()
  76             result = func(*args, **kwargs)
  77             trigger("{0:s}::after".format(event))()
  78             return result
  79 
  80         return register_wrapper
  81 
  82     return _register
  83 
  84 
  85 def trigger(event):
  86     """
  87     Trigger an event if not disabled.
  88     """
  89     global __events, __disabled_events, noop
  90     is_noop = bool(event in __disabled_events or event not in __events)
  91     return noop if is_noop else __events.get(event)
  92 
  93 
  94 def disable(event):
  95     """
  96     Disable an event from firing.
  97     """
  98     global __disabled_events
  99     __disabled_events.add(event)
  100 
  101 
  102 def enable(event):
  103     """
  104     Enable an event to be fired if disabled.
  105     """
  106     global __disabled_events
  107     __disabled_events.remove(event)
  108
  ```
  --- END FILES ---
  
  Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.
  
  Here is an example:
  
  ```diff
  diff --git a/examples/server_async.py b/examples/server_async.py
  --- a/examples/server_async.py
  +++ b/examples/server_async.py
  @@ -313,4 +313,4 @@
   
   
   if __name__ == "__main__":
  -    asyncio.run(run_async_server("."), debug=True)
  +    asyncio.run(run_async_server(), debug=True)
  diff --git a/examples/server_sync.py b/examples/server_sync.py
  --- a/examples/server_sync.py
  +++ b/examples/server_sync.py
  @@ -313,5 +313,5 @@
   
   
   if __name__ == "__main__":
  -    server = run_sync_server(".")
  +    server = run_sync_server()
       server.shutdown()
  
  ```
  
golden_diff: diff --git a/src/pyhf/events.py b/src/pyhf/events.py
  --- a/src/pyhf/events.py
  +++ b/src/pyhf/events.py
  @@ -1,4 +1,5 @@
   import weakref
  +from functools import wraps
   
   __events = {}
   __disabled_events = set([])
  @@ -71,6 +72,7 @@
       # >>>
   
       def _register(func):
  +        @wraps(func)
           def register_wrapper(*args, **kwargs):
               trigger("{0:s}::before".format(event))()
               result = func(*args, **kwargs)
  
verification_info: {"golden_diff": "diff --git a/src/pyhf/events.py b/src/pyhf/events.py\n--- a/src/pyhf/events.py\n+++ b/src/pyhf/events.py\n@@ -1,4 +1,5 @@\n import weakref\n+from functools import wraps\n \n __events = {}\n __disabled_events = set([])\n@@ -71,6 +72,7 @@\n     # >>>\n \n     def _register(func):\n+        @wraps(func)\n         def register_wrapper(*args, **kwargs):\n             trigger(\"{0:s}::before\".format(event))()\n             result = func(*args, **kwargs)\n", "issue": "Top-Level Python API methods don't have docstrings rendered in docs\n# Description\r\n\r\nThe top level Python API methods pages on the docs website doesn't contain any of the rendered docstrings. For example, the `pyhf.set_backend()` API has examples (and it rather important for new users)\r\n\r\nhttps://github.com/scikit-hep/pyhf/blob/e55eea408d7c28e3109338de96252119ac63f87a/src/pyhf/__init__.py#L42-L52\r\n\r\nbut the docs website doesn't show any of this\r\n\r\n![not_rendered](https://user-images.githubusercontent.com/5142394/88368070-def79000-cd52-11ea-9f0e-5acbb4d45c6b.png)\r\n\r\n\r\n# Expected Behavior\r\n\r\nHave the docstrings be rendered in the docs \r\n\r\n# Actual Behavior\r\n\r\nc.f. above\r\n\r\n# Steps to Reproduce\r\n\r\nBuild the docs\r\n\r\n# Checklist\r\n\r\n- [x] Run `git fetch` to get the most up to date version of `master`\r\n- [x] Searched through existing Issues to confirm this is not a duplicate issue\r\n- [x] Filled out the Description, Expected Behavior, Actual Behavior, and Steps to Reproduce sections above or have edited/removed them in a way that fully describes the issue\r\n\n", "before_files": [{"content": "import weakref\n\n__events = {}\n__disabled_events = set([])\n\n\ndef noop(*args, **kwargs):\n    pass\n\n\nclass WeakList(list):\n    def append(self, item):\n        list.append(self, weakref.WeakMethod(item, self.remove))\n\n\nclass Callables(WeakList):\n    def __call__(self, *args, **kwargs):\n        for func in self:\n            # weakref: needs to be de-ref'd first before calling\n            func()(*args, **kwargs)\n\n    def __repr__(self):\n        return \"Callables(%s)\" % list.__repr__(self)\n\n\ndef subscribe(event):\n    \"\"\"\n    This is meant to be used as a decorator.\n    \"\"\"\n    # Example:\n    #\n    # >>> @pyhf.events.subscribe('myevent')\n    # ... def test(a,b):\n    # ...   print a+b\n    # ...\n    # >>> pyhf.events.trigger_myevent(1,2)\n    # 3\n    global __events\n\n    def __decorator(func):\n        __events.setdefault(event, Callables()).append(func)\n        return func\n\n    return __decorator\n\n\ndef register(event):\n    \"\"\"\n    This is meant to be used as a decorator to register a function for triggering events.\n\n    This creates two events: \"<event_name>::before\" and \"<event_name>::after\"\n    \"\"\"\n    # Examples:\n    #\n    # >>> @pyhf.events.register('test_func')\n    # ... def test(a,b):\n    # ...   print a+b\n    # ...\n    # >>> @pyhf.events.subscribe('test_func::before')\n    # ... def precall():\n    # ...   print 'before call'\n    # ...\n    # >>> @pyhf.events.subscribe('test_func::after')\n    # ... def postcall():\n    # ...   print 'after call'\n    # ...\n    # >>> test(1,2)\n    # \"before call\"\n    # 3\n    # \"after call\"\n    # >>>\n\n    def _register(func):\n        def register_wrapper(*args, **kwargs):\n            trigger(\"{0:s}::before\".format(event))()\n            result = func(*args, **kwargs)\n            trigger(\"{0:s}::after\".format(event))()\n            return result\n\n        return register_wrapper\n\n    return _register\n\n\ndef trigger(event):\n    \"\"\"\n    Trigger an event if not disabled.\n    \"\"\"\n    global __events, __disabled_events, noop\n    is_noop = bool(event in __disabled_events or event not in __events)\n    return noop if is_noop else __events.get(event)\n\n\ndef disable(event):\n    \"\"\"\n    Disable an event from firing.\n    \"\"\"\n    global __disabled_events\n    __disabled_events.add(event)\n\n\ndef enable(event):\n    \"\"\"\n    Enable an event to be fired if disabled.\n    \"\"\"\n    global __disabled_events\n    __disabled_events.remove(event)\n", "path": "src/pyhf/events.py"}], "after_files": [{"content": "import weakref\nfrom functools import wraps\n\n__events = {}\n__disabled_events = set([])\n\n\ndef noop(*args, **kwargs):\n    pass\n\n\nclass WeakList(list):\n    def append(self, item):\n        list.append(self, weakref.WeakMethod(item, self.remove))\n\n\nclass Callables(WeakList):\n    def __call__(self, *args, **kwargs):\n        for func in self:\n            # weakref: needs to be de-ref'd first before calling\n            func()(*args, **kwargs)\n\n    def __repr__(self):\n        return \"Callables(%s)\" % list.__repr__(self)\n\n\ndef subscribe(event):\n    \"\"\"\n    This is meant to be used as a decorator.\n    \"\"\"\n    # Example:\n    #\n    # >>> @pyhf.events.subscribe('myevent')\n    # ... def test(a,b):\n    # ...   print a+b\n    # ...\n    # >>> pyhf.events.trigger_myevent(1,2)\n    # 3\n    global __events\n\n    def __decorator(func):\n        __events.setdefault(event, Callables()).append(func)\n        return func\n\n    return __decorator\n\n\ndef register(event):\n    \"\"\"\n    This is meant to be used as a decorator to register a function for triggering events.\n\n    This creates two events: \"<event_name>::before\" and \"<event_name>::after\"\n    \"\"\"\n    # Examples:\n    #\n    # >>> @pyhf.events.register('test_func')\n    # ... def test(a,b):\n    # ...   print a+b\n    # ...\n    # >>> @pyhf.events.subscribe('test_func::before')\n    # ... def precall():\n    # ...   print 'before call'\n    # ...\n    # >>> @pyhf.events.subscribe('test_func::after')\n    # ... def postcall():\n    # ...   print 'after call'\n    # ...\n    # >>> test(1,2)\n    # \"before call\"\n    # 3\n    # \"after call\"\n    # >>>\n\n    def _register(func):\n        @wraps(func)\n        def register_wrapper(*args, **kwargs):\n            trigger(\"{0:s}::before\".format(event))()\n            result = func(*args, **kwargs)\n            trigger(\"{0:s}::after\".format(event))()\n            return result\n\n        return register_wrapper\n\n    return _register\n\n\ndef trigger(event):\n    \"\"\"\n    Trigger an event if not disabled.\n    \"\"\"\n    global __events, __disabled_events, noop\n    is_noop = bool(event in __disabled_events or event not in __events)\n    return noop if is_noop else __events.get(event)\n\n\ndef disable(event):\n    \"\"\"\n    Disable an event from firing.\n    \"\"\"\n    global __disabled_events\n    __disabled_events.add(event)\n\n\ndef enable(event):\n    \"\"\"\n    Enable an event to be fired if disabled.\n    \"\"\"\n    global __disabled_events\n    __disabled_events.remove(event)\n", "path": "src/pyhf/events.py"}]}