fix: Include logging docs in new API docs (getsentry#494)

untitaker · web-flow · commit 296b1bfbdc7c · 2019-09-03T11:54:38.000+02:00
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,9 @@
+========
+Main API
+========
+
+.. inherited-members necessary because of hack for Client and init methods
+
+.. automodule:: sentry_sdk
+    :members:
+    :inherited-members:
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,8 +6,6 @@ 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:
+.. toctree::
+    api
+    integrations
diff --git a/docs/integrations.rst b/docs/integrations.rst
@@ -0,0 +1,14 @@
+============
+Integrations
+============
+
+Logging
+=======
+
+.. module:: sentry_sdk.integrations.logging
+
+.. autofunction:: ignore_logger
+
+.. autoclass:: EventHandler
+
+.. autoclass:: BreadcrumbHandler
diff --git a/sentry_sdk/integrations/logging.py b/sentry_sdk/integrations/logging.py
@@ -27,12 +27,16 @@
 _IGNORED_LOGGERS = set(["sentry_sdk.errors"])
 
 
-def ignore_logger(name):
-    # type: (str) -> None
+def ignore_logger(
+    name  # type: str
+):
+    # type: (...) -> None
     """This disables recording (both in breadcrumbs and as events) calls to
     a logger of a specific name.  Among other uses, many of our integrations
     use this to prevent their actions being recorded as breadcrumbs. Exposed
     to users as a way to quiet spammy loggers.
+
+    :param name: The name of the logger to ignore (same string you would pass to ``logging.getLogger``).
     """
     _IGNORED_LOGGERS.add(name)
 
@@ -146,6 +150,12 @@ def _extra_from_record(record):
 
 
 class EventHandler(logging.Handler, object):
+    """
+    A logging handler that emits Sentry events for each log record
+
+    Note that you do not have to use this class if the logging integration is enabled, which it is by default.
+    """
+
     def emit(self, record):
         # type: (LogRecord) -> Any
         with capture_internal_exceptions():
@@ -204,6 +214,12 @@ def _emit(self, record):
 
 
 class BreadcrumbHandler(logging.Handler, object):
+    """
+    A logging handler that records breadcrumbs for each log record.
+
+    Note that you do not have to use this class if the logging integration is enabled, which it is by default.
+    """
+
     def emit(self, record):
         # type: (LogRecord) -> Any
         with capture_internal_exceptions():
