Improve API docs

[sentrivana]

Problem Statement

Our API docs are in desperate need of some love, e.g.:

• some stuff is not documented at all
  • no docs for the tracing module (spans, transactions)
  • only Logging under Integrations, no other integrations
• some of the top level API docs only mention **kwargs without any further explanation, so people have to dive into the code themselves (Top-level API should list possible args/kwargs explicitly #2199) Allow (some) autocompletion for top-level API #2213
• there's some annoying overlapping happening at times:
  

Solution Brainstorm

• See what relevant parts are undocumented and add them.
• Find an alternative theme where things don't overlap. Change API doc theme #2210
• Make a general effort to improve existing docstrings.
• Add more docstrings where it makes sense.

See also:

• Document scope_kwargs on capture_message  #1086
• tracing.py is not included in https://getsentry.github.io/sentry-python/ #1708
• Top-level API should list possible args/kwargs explicitly #2199

[untitaker]

ways in which sdk api docs differ from arroyo off the top of my head:

1. different theme
2. get rid of sphinx-autodoc-typehints, use sphinx builtin way to render typehints (unclear if it works with type hint comments though)

about the **kwargs situation, we have a glorious hack in the sdk to share kwargs definitions between sentry_sdk.init, sentry_sdk.Client and sentry_sdk.get_options, just gotta reuse that. also works for IDEs

[sentrivana]

@untitaker Trying to wrap my head around the **kwargs hacks. I got the top level capture_event to autocomplete with this:

class CaptureEventArgs(object):
    def __init__(
        self,
        event,  # type: Event
        hint=None,  # type: Optional[str]
        # (...)
        fingerprint=None,  # type: Optional[List[str]]
    ):
        # type: (...) -> None
        pass

# old capture_event
def _capture_event(*args, **kwargs):
    # type: (...) -> Optional[str]
    return Hub.current.capture_event(*args, **kwargs)

# new capture_event
if TYPE_CHECKING:
    class capture_event(CaptureEventArgs):
        pass
else:
    capture_event = (lambda: _capture_event)()

But not sure now how to get this into the api docs correctly. It doesn't show up on its own, I can explicitly tell it to document the capture_event class, but then it shows up in the docs as a class (much surprise). Do you maybe have an idea how to make this work?

Also still figuring out how to also share the CaptureEventArgs with the hub and client methods.

[untitaker]

but then it shows up in the docs as a class (much surprise)

ah yeah. i forgot about that. i think i might have just lived with it back then for get_options. I think it might be possible to re-bind __init__ like so, but that's just a random idea, haven't tried it out:

class capture_event(CaptureEventArgs):
    pass

capture_event = capture_event.__init__

even if sphinx picks that up as a function to document, now the return type will be wrong :(

[sentrivana]

capture_event = capture_event.__init__ works 🙈

Dunno if we can make the return type work. You can just add # type: (...) -> Optional[str] to the fake class __init__ which tricks both vscode and sphinx into suggesting the correct return type, but don't think there's a way to get this past mypy. Will play with it a bit more.

[sentrivana]

Nevermind, TIL @typing.no_type_check

[untitaker]

I believe you can do this:

from typing import TypeVar, TYPE_CHECKING, Generic, Optional
from typing_extensions import reveal_type

if TYPE_CHECKING:
    BogusBaseclass = TypeVar("BogusBaseclass")
else:
    BogusBaseclass = object

class CaptureEventArgs(Generic[BogusBaseclass]):
    def __init__(a: int) -> BogusBaseclass:  # type: ignore
        pass

class _capture_event(CaptureEventArgs[Optional[str]]):
    pass

capture_event = _capture_event.__init__

reveal_type(capture_event)

[untitaker]

Updated above example to be self-contained -- you also have to make __init__ no longer take self to make it work. Maybe it is not a good idea!

[untitaker]

Actually I think it might be good enough to re-bind Hub.capture_event into global scope to copy its args, like this:

class Hub:
    def capture_event(self, event, hints=None) -> Optional[str]:
        ...


if TYPE_CHECKING:
    capture_event = Hub().capture_event

else:
    def capture_event(*args, **kwargs): ...

[sentrivana]

Was able to get both autocompletion and Sphinx working with a variation of your last idea:

from functools import partial

if TYPE_CHECKING:
    capture_event = partial(Hub.capture_event, None)
else:
    def capture_event(*args, **kwargs):
        return Hub.current.capture_event(*args, **kwargs)

Without the partial sphinx refuses to process the function, complaining about an IndexError, my best guess is that it doesn't know what how to deal with Hub.capture_event being a bound method. But with the partial it looks good.

Thanks for the help, much appreciated!

[untitaker]

hideous, i love it