Organize the documentation (#483)

pydantic · Oct 9, 2024 · b204ba4 · b204ba4
1 parent 9e47aa7
commit b204ba4
Show file tree

Hide file tree

Showing 21 changed files with 44 additions and 36 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -312,6 +312,7 @@ First release from new repo!
 [v0.53.0]: https://github.com/pydantic/logfire/compare/v0.52.0...v0.53.0
 [v0.52.0]: https://github.com/pydantic/logfire/compare/v0.51.0...v0.52.0
 [v0.51.0]: https://github.com/pydantic/logfire/compare/v0.50.1...v0.51.0
+[v0.50.1]: https://github.com/pydantic/logfire/compare/v0.50.0...v0.50.1
 [v0.50.0]: https://github.com/pydantic/logfire/compare/v0.49.1...v0.50.0
 [v0.49.1]: https://github.com/pydantic/logfire/compare/v0.49.0...v0.49.1
 [v0.49.0]: https://github.com/pydantic/logfire/compare/v0.48.1...v0.49.0

diff --git a/docs/api/integrations/logging.md b/docs/api/integrations/logging.md
diff --git a/docs/api/integrations/structlog.md b/docs/api/integrations/structlog.md
diff --git a/docs/help.md b/docs/help.md
@@ -22,7 +22,7 @@ The [usage documentation](index.md) is the most complete guide on how to get sta
 
 ## :material-api: SDK API Documentation
 
-The [SDK API documentation](api/logfire.md) give reference docs for the **Logfire** SDK.
+The [SDK API documentation](reference/api/logfire.md) give reference docs for the **Logfire** SDK.
 
 ## :material-email: Email
 

diff --git a/docs/api/exceptions.md → docs/reference/api/exceptions.md b/docs/api/exceptions.md → docs/reference/api/exceptions.md
diff --git a/docs/api/logfire.md → docs/reference/api/logfire.md b/docs/api/logfire.md → docs/reference/api/logfire.md
diff --git a/docs/api/propagate.md → docs/reference/api/propagate.md b/docs/api/propagate.md → docs/reference/api/propagate.md
diff --git a/docs/api/integrations/pydantic.md → docs/reference/api/pydantic.md b/docs/api/integrations/pydantic.md → docs/reference/api/pydantic.md
diff --git a/docs/api/sampling.md → docs/reference/api/sampling.md b/docs/api/sampling.md → docs/reference/api/sampling.md
diff --git a/docs/api/testing.md → docs/reference/api/testing.md b/docs/api/testing.md → docs/reference/api/testing.md
diff --git a/docs/examples.md → docs/reference/examples.md b/docs/examples.md → docs/reference/examples.md
@@ -1,28 +1,24 @@
----
-hide:
-- navigation
----
 # Examples
 
 These are working, stand-alone apps and projects that you can clone, spin up locally and play around with to get a feel for the different capabilities of Logfire.
 
 **Got a suggestion?**
 
-If you want to see an example of a particular language or library, [get in touch](help.md).
+If you want to see an example of a particular language or library, [get in touch](../help.md).
 
 ## Python
 
 ### Flask and SQLAlchemy example
 
-This example is a simple Python financial calculator app using Flask and SQLAlchemy which is instrumented using the appropriate integrations as well as [auto-tracing](guides/onboarding-checklist/add-auto-tracing.md). If you spin up the server locally and interact with the calculator app, you'll be able to see traces come in automatically:
+This example is a simple Python financial calculator app using Flask and SQLAlchemy which is instrumented using the appropriate integrations as well as [auto-tracing](../guides/onboarding-checklist/add-auto-tracing.md). If you spin up the server locally and interact with the calculator app, you'll be able to see traces come in automatically:
 
-![Flask and SQLAlchemy example](images/logfire-screenshot-examples-flask-sqlalchemy.png)
+![Flask and SQLAlchemy example](../images/logfire-screenshot-examples-flask-sqlalchemy.png)
 
 [See it on GitHub :material-open-in-new:](https://github.com/pydantic/logfire/tree/main/examples/python/flask-sqlalchemy/){:target="_blank"}
 
 ## JavaScript
 
-Currently we only have a Python SDK, but the Logfire backend and UI support data sent by any OpenTelemetry client. See the [alternative clients guide](guides/advanced/alternative-clients.md) for details on setting up OpenTelemetry in any language. We're working on a JavaScript SDK, but in the meantime here are some examples of using plain OpenTelemetry in JavaScript:
+Currently we only have a Python SDK, but the Logfire backend and UI support data sent by any OpenTelemetry client. See the [alternative clients guide](../guides/advanced/alternative-clients.md) for details on setting up OpenTelemetry in any language. We're working on a JavaScript SDK, but in the meantime here are some examples of using plain OpenTelemetry in JavaScript:
 
 ### Cloudflare worker example
 

diff --git a/docs/reference/index.md b/docs/reference/index.md
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -79,6 +79,9 @@ Logfire is built on top of OpenTelemetry, which means that it supports all the l
 Still, we are planning to create custom SDKs for JavaScript, TypeScript, and Rust, and make sure that the
 attributes are displayed in a nice way in the Logfire UI — as they are for Python.
 
+For now, you can check our [Alternative Clients](guides/advanced/alternative-clients.md) section to see how
+you can send data to Logfire from other languages.
+
 See [this GitHub issue][language-support-gh-issue] for more information.
 
 ### Automatic anomaly detection

diff --git a/logfire-api/logfire_api/__init__.py b/logfire-api/logfire_api/__init__.py
@@ -1,10 +1,9 @@
 from __future__ import annotations
 
-from contextlib import contextmanager
 import importlib
 import sys
-from typing import TYPE_CHECKING, ContextManager, Literal
-from contextlib import nullcontext
+from contextlib import contextmanager, nullcontext
+from typing import Any, ContextManager, Literal, TYPE_CHECKING
 from unittest.mock import MagicMock
 
 try:
@@ -166,6 +165,8 @@ def shutdown(self, *args, **kwargs) -> None: ...
         instrument_system_metrics = DEFAULT_LOGFIRE_INSTANCE.instrument_system_metrics
         shutdown = DEFAULT_LOGFIRE_INSTANCE.shutdown
 
+        def loguru_handler() -> dict[str, Any]: ...
+
         def no_auto_trace(x):
             return x
 

diff --git a/logfire-api/logfire_api/__init__.pyi b/logfire-api/logfire_api/__init__.pyi
@@ -10,8 +10,9 @@ from .integrations.logging import LogfireLoggingHandler as LogfireLoggingHandler
 from .integrations.structlog import LogfireProcessor as StructlogProcessor
 from .version import VERSION as VERSION
 from logfire.sampling import SamplingOptions as SamplingOptions
+from typing import Any
 
-__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_pydantic', 'instrument_fastapi', 'instrument_openai', 'instrument_anthropic', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_sqlalchemy', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_system_metrics', 'AutoTraceModule', 'with_tags', 'with_settings', 'shutdown', 'load_spans_from_file', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'SamplingOptions', 'MetricsOptions']
+__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_pydantic', 'instrument_fastapi', 'instrument_openai', 'instrument_anthropic', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_sqlalchemy', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_system_metrics', 'AutoTraceModule', 'with_tags', 'with_settings', 'shutdown', 'load_spans_from_file', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions']
 
 DEFAULT_LOGFIRE_INSTANCE = Logfire()
 span = DEFAULT_LOGFIRE_INSTANCE.span
@@ -49,4 +50,11 @@ warn = DEFAULT_LOGFIRE_INSTANCE.warn
 error = DEFAULT_LOGFIRE_INSTANCE.error
 fatal = DEFAULT_LOGFIRE_INSTANCE.fatal
 exception = DEFAULT_LOGFIRE_INSTANCE.exception
+
+def loguru_handler() -> dict[str, Any]:
+    """Create a **Logfire** handler for Loguru.
+
+    Returns:
+        A dictionary with the handler and format for Loguru.
+    """
 __version__ = VERSION
diff --git a/logfire-api/logfire_api/_internal/config.pyi b/logfire-api/logfire_api/_internal/config.pyi
@@ -77,7 +77,11 @@ class MetricsOptions:
 
 @dataclass
 class CodeSource:
-    """Settings for the source code of the project."""
+    """Settings for the source code of the project.
+
+    !!! Warning
+        This setting is experimental, and may change in the future!
+    """
     repository: str
     revision: str
     root_path: str
@@ -111,6 +115,8 @@ def configure(*, send_to_logfire: bool | Literal['if-token-present'] | None = No
             Defaults to `True` if and only if the Python version is at least 3.11.
         sampling: Sampling options. See the [sampling guide](https://logfire.pydantic.dev/docs/guides/advanced/sampling/).
         code_source: Settings for the source code of the project.
+            !!! Warning
+                This setting is experimental, and may change in the future!
         advanced: Advanced options primarily used for testing by Logfire developers.
     """
 

diff --git a/logfire/__init__.py b/logfire/__init__.py
@@ -142,6 +142,7 @@ def loguru_handler() -> dict[str, Any]:
     'suppress_instrumentation',
     'StructlogProcessor',
     'LogfireLoggingHandler',
+    'loguru_handler',
     'SamplingOptions',
     'MetricsOptions',
 )
diff --git a/logfire/integrations/loguru.py b/logfire/integrations/loguru.py
@@ -1,4 +1,4 @@
-"""Integration with Loguru."""
+"""Integration with [Loguru](https://github.com/Delgan/loguru)."""
 
 from __future__ import annotations
 

diff --git a/logfire/integrations/structlog.py b/logfire/integrations/structlog.py
@@ -1,4 +1,4 @@
-"""Logfire processor for structlog."""
+"""Logfire processor for [structlog](https://www.structlog.org/en/stable/)."""
 
 from __future__ import annotations
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -138,21 +138,17 @@ nav:
       - Use Cases:
           - Web Frameworks: integrations/use-cases/web-frameworks.md
   - Reference:
-      - Reference: reference/index.md
+      - Examples: reference/examples.md
       - Configuration: reference/configuration.md
       - Organization Structure: reference/organization-structure.md
       - SDK CLI: reference/cli.md
-  - SDK API:
-      - Logfire: api/logfire.md
-      - Testing: api/testing.md
-      - Sampling: api/sampling.md
-      - Propagate: api/propagate.md
-      - Exceptions: api/exceptions.md
-      - Integrations:
-          - api/integrations/pydantic.md
-          - api/integrations/logging.md
-          - api/integrations/structlog.md
-  - Examples: examples.md
+      - SDK API:
+          - Logfire: reference/api/logfire.md
+          - Testing: reference/api/testing.md
+          - Sampling: reference/api/sampling.md
+          - Propagate: reference/api/propagate.md
+          - Exceptions: reference/api/exceptions.md
+          - Pydantic: reference/api/pydantic.md
   - Help: help.md
   - Roadmap: roadmap.md
   - Legal:

diff --git a/tests/test_logfire_api.py b/tests/test_logfire_api.py
@@ -152,6 +152,10 @@ def func() -> None: ...
     logfire_api.LogfireLoggingHandler()
     logfire__all__.remove('LogfireLoggingHandler')
 
+    assert hasattr(logfire_api, 'loguru_handler')
+    logfire_api.loguru_handler()
+    logfire__all__.remove('loguru_handler')
+
     assert hasattr(logfire_api, 'StructlogProcessor')
     logfire_api.StructlogProcessor()
     logfire__all__.remove('StructlogProcessor')