Improve references in the main docstrings (#131)

Author: Kludex

logfire/_internal/main.py

@@ -218,9 +218,10 @@ def trace(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
         """
         if any(k.startswith('_') for k in attributes):
             raise ValueError('Attribute keys cannot start with an underscore.')
@@ -247,9 +248,10 @@ def debug(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
         """
         if any(k.startswith('_') for k in attributes):
             raise ValueError('Attribute keys cannot start with an underscore.')
@@ -276,9 +278,10 @@ def info(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
         """
         if any(k.startswith('_') for k in attributes):
             raise ValueError('Attribute keys cannot start with an underscore.')
@@ -305,9 +308,10 @@ def notice(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
         """
         if any(k.startswith('_') for k in attributes):
             raise ValueError('Attribute keys cannot start with an underscore.')
@@ -334,9 +338,10 @@ def warn(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
         """
         if any(k.startswith('_') for k in attributes):
             raise ValueError('Attribute keys cannot start with an underscore.')
@@ -363,9 +368,10 @@ def error(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
         """
         if any(k.startswith('_') for k in attributes):
             raise ValueError('Attribute keys cannot start with an underscore.')
@@ -392,9 +398,10 @@ def fatal(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
         """
         if any(k.startswith('_') for k in attributes):
             raise ValueError('Attribute keys cannot start with an underscore.')
@@ -417,7 +424,7 @@ def exception(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             _tags: An optional sequence of tags to include in the log.
-            _exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
         """
         if any(k.startswith('_') for k in attributes):  # pragma: no cover
@@ -450,7 +457,6 @@ def span(
             _tags: An optional sequence of tags to include in the span.
             _level: An optional log level name.
             _stack_offset: The stack level offset to use when collecting stack info, defaults to `3`.
-
             attributes: The arguments to include in the span and format the message template with.
                 Attributes starting with an underscore are not allowed.
         """
@@ -519,16 +525,20 @@ def log(
             msg_template: The message to log.
             attributes: The attributes to bind to the log.
             tags: An optional sequence of tags to include in the log.
-            exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
+            exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
-                Set to True to use the currently handled exception.
+
+                Set to `True` to use the currently handled exception.
             stack_offset: The stack level offset to use when collecting stack info, also affects the warning which
                 message formatting might emit, defaults to `0` which means the stack info will be collected from the
-                position where `logfire.log` was called.
+                position where [`logfire.log`][logfire.Logfire.log] was called.
             console_log: Whether to log to the console, defaults to `True`.
-            custom_scope_suffix: A custom suffix to append to `logfire.`, should only be used when you're using
-                logfire to instrument another library like structlog or loguru.
-                See `TraceProvider.get_tracer(instrumenting_module_name)` docstring for more info.
+            custom_scope_suffix: A custom suffix to append to `logfire.` e.g. `logfire.loguru`.
+
+                It should only be used when instrumenting another library with Logfire, such as structlog or loguru.
+
+                See the `instrumenting_module_name` parameter on
+                [TracerProvider.get_tracer][opentelemetry.sdk.trace.TracerProvider.get_tracer] for more info.
         """
         stack_offset = (self._stack_offset if stack_offset is None else stack_offset) + 2
         stack_info = get_caller_stack_info(stack_offset)
@@ -639,11 +649,14 @@ def with_settings(
             tags: Sequence of tags to include in the log.
             stack_offset: The stack level offset to use when collecting stack info, also affects the warning which
                 message formatting might emit, defaults to `0` which means the stack info will be collected from the
-                position where `logfire.log` was called.
+                position where [`logfire.log`][logfire.Logfire.log] was called.
             console_log: Whether to log to the console, defaults to `True`.
-            custom_scope_suffix: A custom suffix to append to `logfire.`, should only be used when you're using
-                logfire to instrument another library like structlog or loguru.
-                See `TraceProvider.get_tracer(instrumenting_module_name)` docstring for more info.
+            custom_scope_suffix: A custom suffix to append to `logfire.` e.g. `logfire.loguru`.
+
+                It should only be used when instrumenting another library with Logfire, such as structlog or loguru.
+
+                See the `instrumenting_module_name` parameter on
+                [TracerProvider.get_tracer][opentelemetry.sdk.trace.TracerProvider.get_tracer] for more info.
 
         Returns:
             A new Logfire instance with the given settings applied.
@@ -1081,7 +1094,7 @@ def shutdown(self, timeout_millis: int = 30_000, flush: bool = True) -> bool:  #
             flush: Whether to flush remaining spans and metrics before shutting down.
 
         Returns:
-            False if the timeout was reached before the shutdown was completed, True otherwise.
+            `False` if the timeout was reached before the shutdown was completed, `True` otherwise.
         """
         start = time()
         if flush:  # pragma: no branch