docs: Document top-level start_transaction function (#2924)

Although the @scopemethod decorator should take care of adding this documentation comment to start_transaction, the decorator does not appear to work when hovering over the sentry_sdk.start_transaction function in VSCode. Adding the doc comment explicitly allows the documentation to be shown when hovering in VSCode, but it does not change the output of our API docs, which still uses the @scopemethod output.

This is the final PR in this repository that addresses getsentry/sentry-docs#5082; the last step to closing that issue will be to add a link in the docs to start_transaction in our API docs. We can only do this once 2.0 is released.

Author: szokeasaurusrex

sentry_sdk/api.py

@@ -288,6 +288,36 @@ def start_transaction(
     **kwargs,  # type: Unpack[TransactionKwargs]
 ):
     # type: (...) -> Union[Transaction, NoOpSpan]
+    """
+    Start and return a transaction on the current scope.
+
+    Start an existing transaction if given, otherwise create and start a new
+    transaction with kwargs.
+
+    This is the entry point to manual tracing instrumentation.
+
+    A tree structure can be built by adding child spans to the transaction,
+    and child spans to other spans. To start a new child span within the
+    transaction or any span, call the respective `.start_child()` method.
+
+    Every child span must be finished before the transaction is finished,
+    otherwise the unfinished spans are discarded.
+
+    When used as context managers, spans and transactions are automatically
+    finished at the end of the `with` block. If not using context managers,
+    call the `.finish()` method.
+
+    When the transaction is finished, it will be sent to Sentry with all its
+    finished child spans.
+
+    :param transaction: The transaction to start. If omitted, we create and
+        start a new transaction.
+    :param instrumenter: This parameter is meant for internal use only.
+    :param custom_sampling_context: The transaction's custom sampling context.
+    :param kwargs: Optional keyword arguments to be passed to the Transaction
+        constructor. See :py:class:`sentry_sdk.tracing.Transaction` for
+        available arguments.
+    """
     return Scope.get_current_scope().start_transaction(
         transaction, instrumenter, custom_sampling_context, **kwargs
     )