doc: Improve new API docs (#414)

* fix: Enable typing imports for docs

* doc: More method docs, new doc theme

* fix: Fix docs for Client

Author: untitaker

docs-requirements.txt

@@ -1,4 +1,4 @@
 sphinx
 sphinx-rtd-theme
-git+https://github.com/untitaker/sphinx-autodoc-typehints@feat/type-hint-comments
+git+https://github.com/agronholm/sphinx-autodoc-typehints
 typed_ast

docs/conf.py

@@ -3,6 +3,10 @@
 import os
 import sys
 
+import typing
+
+typing.TYPE_CHECKING = True
+
 #
 # Configuration file for the Sphinx documentation builder.
 #
@@ -36,6 +40,7 @@
     "sphinx_autodoc_typehints",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -74,19 +79,7 @@
 
 on_rtd = os.environ.get("READTHEDOCS", None) == "True"
 
-try:
-    import sphinx_rtd_theme
-
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-except ImportError:
-    html_theme = "default"
-    if not on_rtd:
-        print("-" * 74)
-        print(
-            "Warning: sphinx-rtd-theme not installed, building with default " "theme."
-        )
-        print("-" * 74)
+html_theme = "alabaster"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -188,3 +181,5 @@
 
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ["search.html"]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

docs/index.rst

@@ -6,5 +6,9 @@ This is the API documentation for `Sentry's Python SDK
 <https://sentry.io/for/python/>`_. For full documentation and other resources
 visit the `GitHub repository <https://github.com/getsentry/sentry-python>`_.
 
+.. inherited-members necessary because of hack for Client and init methods
+
 .. automodule:: sentry_sdk
     :members:
+
+    :inherited-members:

sentry_sdk/_compat.py

@@ -1,6 +1,7 @@
 import sys
 
-MYPY = False
+from sentry_sdk._types import MYPY
+
 if MYPY:
     from typing import Optional
     from typing import Tuple

sentry_sdk/_types.py

@@ -0,0 +1,28 @@
+try:
+    from typing import TYPE_CHECKING as MYPY
+except ImportError:
+    MYPY = False
+
+
+if MYPY:
+    from types import TracebackType
+    from typing import Any
+    from typing import Callable
+    from typing import Dict
+    from typing import Optional
+    from typing import Tuple
+    from typing import Type
+
+    ExcInfo = Tuple[
+        Optional[Type[BaseException]], Optional[BaseException], Optional[TracebackType]
+    ]
+
+    Event = Dict[str, Any]
+    Hint = Dict[str, Any]
+
+    Breadcrumb = Dict[str, Any]
+    BreadcrumbHint = Dict[str, Any]
+
+    EventProcessor = Callable[[Event, Hint], Optional[Event]]
+    ErrorProcessor = Callable[[Event, ExcInfo], Optional[Event]]
+    BreadcrumbProcessor = Callable[[Breadcrumb, BreadcrumbHint], Optional[Breadcrumb]]

sentry_sdk/api.py

@@ -4,16 +4,17 @@
 from sentry_sdk.hub import Hub
 from sentry_sdk.scope import Scope
 
-MYPY = False
+from sentry_sdk._types import MYPY
+
 if MYPY:
     from typing import Any
     from typing import Optional
     from typing import overload
     from typing import Callable
     from typing import TypeVar
-    from contextlib import ContextManager
+    from typing import ContextManager
 
-    from sentry_sdk.utils import Event, Hint, Breadcrumb, BreadcrumbHint
+    from sentry_sdk._types import Event, Hint, Breadcrumb, BreadcrumbHint
 
     T = TypeVar("T")
     F = TypeVar("F", bound=Callable[..., Any])

sentry_sdk/client.py

@@ -2,6 +2,7 @@
 import uuid
 import random
 from datetime import datetime
+import socket
 
 from sentry_sdk._compat import string_types, text_type, iteritems
 from sentry_sdk.utils import (
@@ -17,15 +18,16 @@
 from sentry_sdk.integrations import setup_integrations
 from sentry_sdk.utils import ContextVar
 
-MYPY = False
+from sentry_sdk._types import MYPY
+
 if MYPY:
     from typing import Any
     from typing import Callable
     from typing import Dict
     from typing import Optional
 
     from sentry_sdk.scope import Scope
-    from sentry_sdk.utils import Event, Hint
+    from sentry_sdk._types import Event, Hint
 
 
 _client_init_debug = ContextVar("client_init_debug")
@@ -58,6 +60,9 @@ def _get_options(*args, **kwargs):
     if rv["environment"] is None:
         rv["environment"] = os.environ.get("SENTRY_ENVIRONMENT")
 
+    if rv["server_name"] is None and hasattr(socket, "gethostname"):
+        rv["server_name"] = socket.gethostname()
+
     return rv  # type: ignore
 
 
@@ -206,17 +211,20 @@ def _should_capture(
 
         return True
 
-    def capture_event(self, event, hint=None, scope=None):
-        # type: (Dict[str, Any], Optional[Any], Optional[Scope]) -> Optional[str]
+    def capture_event(
+        self,
+        event,  # type: Event
+        hint=None,  # type: Optional[Hint]
+        scope=None,  # type: Optional[Scope]
+    ):
+        # type: (...) -> Optional[str]
         """Captures an event.
 
-        This takes the ready made event and an optional hint and scope.  The
-        hint is internally used to further customize the representation of the
-        error.  When provided it's a dictionary of optional information such
-        as exception info.
+        :param event: A ready-made event that can be directly sent to Sentry.
+
+        :param hint: Contains metadata about the event that can be read from `before_send`, such as the original exception object or a HTTP request object.
 
-        If the transport is not set nothing happens, otherwise the return
-        value of this function will be the ID of the captured event.
+        :returns: An event ID. May be `None` if there is no DSN set or of if the SDK decided to discard the event for other reasons. In such situations setting `debug=True` on `init()` may help.
         """
         if self.transport is None:
             return None
@@ -233,26 +241,33 @@ def capture_event(self, event, hint=None, scope=None):
         self.transport.capture_event(event)
         return rv
 
-    def close(self, timeout=None, callback=None):
-        # type: (Optional[float], Optional[Callable[[int, float], None]]) -> None
+    def close(
+        self,
+        timeout=None,  # type: Optional[float]
+        callback=None,  # type: Optional[Callable[[int, float], None]]
+    ):
+        # type: (...) -> None
         """
         Close the client and shut down the transport. Arguments have the same
-        semantics as `self.flush()`.
+        semantics as :py:meth:`Client.flush`.
         """
         if self.transport is not None:
             self.flush(timeout=timeout, callback=callback)
             self.transport.kill()
             self.transport = None
 
-    def flush(self, timeout=None, callback=None):
-        # type: (Optional[float], Optional[Callable[[int, float], None]]) -> None
+    def flush(
+        self,
+        timeout=None,  # type: Optional[float]
+        callback=None,  # type: Optional[Callable[[int, float], None]]
+    ):
+        # type: (...) -> None
         """
-        Wait `timeout` seconds for the current events to be sent. If no
-        `timeout` is provided, the `shutdown_timeout` option value is used.
+        Wait for the current events to be sent.
+
+        :param timeout: Wait for at most `timeout` seconds. If no `timeout` is provided, the `shutdown_timeout` option value is used.
 
-        The `callback` is invoked with two arguments: the number of pending
-        events and the configured timeout.  For instance the default atexit
-        integration will use this to render out a message on stderr.
+        :param callback: Is invoked with the number of pending events and the configured timeout.
         """
         if self.transport is not None:
             if timeout is None:
@@ -268,7 +283,8 @@ def __exit__(self, exc_type, exc_value, tb):
         self.close()
 
 
-MYPY = False
+from sentry_sdk._types import MYPY
+
 if MYPY:
     # Make mypy, PyCharm and other static analyzers think `get_options` is a
     # type to have nicer autocompletion for params.

sentry_sdk/consts.py

@@ -1,6 +1,5 @@
-import socket
+from sentry_sdk._types import MYPY
 
-MYPY = False
 if MYPY:
     from typing import Optional
     from typing import Callable
@@ -13,10 +12,7 @@
     from sentry_sdk.transport import Transport
     from sentry_sdk.integrations import Integration
 
-    from sentry_sdk.utils import Event, EventProcessor, BreadcrumbProcessor
-
-
-DEFAULT_SERVER_NAME = socket.gethostname() if hasattr(socket, "gethostname") else None
+    from sentry_sdk._types import Event, EventProcessor, BreadcrumbProcessor
 
 
 # This type exists to trick mypy and PyCharm into thinking `init` and `Client`
@@ -29,7 +25,7 @@ def __init__(
         max_breadcrumbs=100,  # type: int
         release=None,  # type: Optional[str]
         environment=None,  # type: Optional[str]
-        server_name=DEFAULT_SERVER_NAME,  # type: Optional[str]
+        server_name=None,  # type: Optional[str]
         shutdown_timeout=2,  # type: int
         integrations=[],  # type: List[Integration]
         in_app_include=[],  # type: List[str]