From da2daa617c3739a03bd3fc3660d5137db7a3db38 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 23 Jan 2026 20:13:08 +0000 Subject: [PATCH] Refactor documentation: Fix lists, nav, formatting and duplicates - docs/conf.py: Enabled advanced navigation (indexes, top, sections) and reformatted. - docs/index.rst: Simplified landing page and updated Next Steps. - docs/_snippets: Updated plugin/module lists. - docs/modules/index.rst: Renamed title. - docs/guides/user_tutorial.rst: Added core module links. - packages/.../interfaces.py: Refactored docstrings to fix duplicate object warnings. - .github/workflows/deploy-docs.yml: Added PR trigger. --- .github/workflows/deploy-docs.yml | 3 + docs/_snippets/core_modules_list.rst | 2 +- docs/_snippets/plugins_list.rst | 7 +- docs/conf.py | 11 ++- docs/guides/user_tutorial.rst | 6 ++ docs/index.rst | 75 +++---------------- docs/modules/index.rst | 4 +- .../structum/src/structum/auth/interfaces.py | 13 ++-- .../src/structum/database/interfaces.py | 14 ++-- 9 files changed, 52 insertions(+), 83 deletions(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 506d2b66..7800de06 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -7,6 +7,9 @@ on: push: branches: - main + pull_request: + branches: + - main workflow_dispatch: # Manual trigger concurrency: diff --git a/docs/_snippets/core_modules_list.rst b/docs/_snippets/core_modules_list.rst index 130ced0e..8739ac66 100644 --- a/docs/_snippets/core_modules_list.rst +++ b/docs/_snippets/core_modules_list.rst @@ -1,5 +1,5 @@ +- :doc:`modules/auth` - Authentication and authorization interfaces - :doc:`modules/configuration` - Multi-layer config with dot-notation -- :doc:`modules/auth` - JWT, RBAC, password hashing - :doc:`modules/database` - Connection pooling, transactions, health checks - :doc:`modules/logging` - Core Logging Protocols (Zero-Dep) - :doc:`modules/monitoring` - Core Metrics Protocols (Zero-Dep) diff --git a/docs/_snippets/plugins_list.rst b/docs/_snippets/plugins_list.rst index 958f6e12..5ac9b8a8 100644 --- a/docs/_snippets/plugins_list.rst +++ b/docs/_snippets/plugins_list.rst @@ -1,7 +1,8 @@ -- :doc:`plugins/dynaconf` - Enterprise configuration engine +- :doc:`plugins/auth` - Authentication implementations - :doc:`plugins/bootstrap` - Application lifecycle management +- :doc:`plugins/cli-tools` - Advanced development tools +- :doc:`plugins/database` - SQLAlchemy/PostgreSQL providers - :doc:`plugins/di` - DI for FastAPI +- :doc:`plugins/dynaconf` - Enterprise configuration engine - :doc:`plugins/fastapi` - FastAPI web framework integration -- :doc:`plugins/auth` - Authentication implementations -- :doc:`plugins/database` - SQLAlchemy/PostgreSQL providers - :doc:`plugins/observability` - Feature-rich Logging & Prometheus (Structlog+OTEL) diff --git a/docs/conf.py b/docs/conf.py index a707ae0a..ce9e67f6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -73,7 +73,16 @@ "accent": "indigo", }, ], - "features": ["navigation.expand", "navigation.tabs"], + "features": [ + "navigation.expand", + "navigation.tabs", + "navigation.top", + "navigation.sections", + "navigation.indexes", + "navigation.instant", # Improve navigation speed + "header.autohide", # Auto-hide header on scroll + "search.share", # Share search results + ], "globaltoc_collapse": False, } diff --git a/docs/guides/user_tutorial.rst b/docs/guides/user_tutorial.rst index b80b0e6a..3176bd95 100644 --- a/docs/guides/user_tutorial.rst +++ b/docs/guides/user_tutorial.rst @@ -90,6 +90,8 @@ Create ``config.json``: } } +See full documentation: :doc:`/modules/configuration` + 2.2 Logging (Core) ~~~~~~~~~~~~~~~~~~ @@ -105,6 +107,8 @@ The core logging facade works without plugins. log.warning("Low memory", extra={"available_mb": 128}) log.error("Connection failed", exc_info=True) +See full documentation: :doc:`/modules/logging` + 2.3 Authentication Interfaces (Core) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -132,6 +136,8 @@ Core provides abstract interfaces that you can implement yourself: def roles(self) -> list[str]: return self._roles +See full documentation: :doc:`/modules/auth` + --- Enhance with Plugins diff --git a/docs/index.rst b/docs/index.rst index e841483b..09e822c7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -128,9 +128,6 @@ Quick Install (From Source) Quick Start ----------- -1. Minimal Example (Core Only) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The configuration system works out-of-the-box without any setup using ``structum``: .. code-block:: python @@ -150,63 +147,7 @@ The configuration system works out-of-the-box without any setup using ``structum print(f"Server starting on {host}:{port}") -2. Production Example (With Plugins) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Full-featured application using ``structum`` (Meta): - -.. code-block:: python - - from structum.config import set_config_provider, get_config - from structum.plugins.dynaconf import DynaconfConfigProvider - from structum.plugins.observability import setup_logging, get_logger - from structum.plugins.bootstrap import SystemBootstrapper, EnvValidator - - def setup_application(): - """ - Initialize Structum with production features. - """ - # 1. Validation: Ensure environment is ready - boot = SystemBootstrapper() - boot.add_validator(EnvValidator(required=["APP_ENV", "DB_URL"])) - boot.run_or_exit() - - # 2. Configuration: Load multi-layer config - provider = DynaconfConfigProvider(root_path=".", env_prefix="MYAPP") - set_config_provider(provider) - - # 3. Observability: Setup structured logging - setup_logging() - - get_logger(__name__).info("Application initialized") - - if __name__ == "__main__": - setup_application() - -Project Structure ------------------ - -Structum uses a **monorepo** architecture with distributed packages: - -.. code-block:: text - - structum/ - ├── packages/ # Distribution Packages - │ ├── core/ # [structum] Protocols & Base - │ ├── meta/ # [structum] Meta-package bundle - │ ├── dynaconf/ # [structum-dynaconf] Plugin - │ ├── observability/ # [structum-observability] Plugin - │ ├── auth/ # [structum-auth] Plugin - │ ├── database/ # [structum-database] Plugin - │ ├── di/ # [structum-di] Plugin - │ └── bootstrap/ # [structum-bootstrap] Plugin - │ - ├── examples/ # Example applications - │ ├── 01-logging-basics/ - │ ├── 02-observability-full/ - │ └── ... - │ - └── pyproject.toml # Workspace Orchestrator +For a complete guide on building a production-ready application with plugins, see the :doc:`guides/user_tutorial`. Architecture Overview --------------------- @@ -289,9 +230,17 @@ As projects grow, you'll reinvent configuration management, logging setup, healt Next Steps ---------- -1. :doc:`guides/configuration_getting_started` - Deep dive into configuration management -2. :doc:`guides/enterprise_architecture` - Building production systems -3. :doc:`reference/core` - Complete API documentation +1. :doc:`guides/user_tutorial` - Build your first application +2. **Explore Core Modules**: + + - :doc:`modules/configuration` + - :doc:`modules/logging` + - :doc:`modules/auth` + - :doc:`modules/database` + - :doc:`modules/monitoring` + +3. :doc:`guides/enterprise_architecture` - Building production systems +4. :doc:`reference/core` - Complete API documentation Support ------- diff --git a/docs/modules/index.rst b/docs/modules/index.rst index cd463ceb..71fafabb 100644 --- a/docs/modules/index.rst +++ b/docs/modules/index.rst @@ -1,5 +1,5 @@ -API Modules Reference -===================== +Core Modules +============ Core API reference documentation for Structum's fundamental modules. diff --git a/packages/structum/src/structum/auth/interfaces.py b/packages/structum/src/structum/auth/interfaces.py index cb984bb9..267940d5 100644 --- a/packages/structum/src/structum/auth/interfaces.py +++ b/packages/structum/src/structum/auth/interfaces.py @@ -30,12 +30,6 @@ class TokenPair: """ Data class containing JWT access and refresh token pair. - Attributes: - access_token (str): Short-lived JWT access token for API requests. - refresh_token (str): Long-lived token for obtaining new access tokens. - token_type (str): Token type, typically "bearer" for JWT. Defaults to "bearer". - expires_at (datetime | None): Expiration timestamp for access token, if available. - Example: Creating and using token pair:: @@ -59,9 +53,16 @@ class TokenPair: """ access_token: str + """Short-lived JWT access token for API requests.""" + refresh_token: str + """Long-lived token for obtaining new access tokens.""" + token_type: str = "bearer" + """Token type, typically "bearer" for JWT. Defaults to "bearer".""" + expires_at: datetime | None = None + """Expiration timestamp for access token, if available.""" @runtime_checkable diff --git a/packages/structum/src/structum/database/interfaces.py b/packages/structum/src/structum/database/interfaces.py index 454808cd..fde3e7ce 100644 --- a/packages/structum/src/structum/database/interfaces.py +++ b/packages/structum/src/structum/database/interfaces.py @@ -54,13 +54,6 @@ class HealthCheckResult: """ Data class representing database health check results. - Attributes: - status (HealthStatus): Overall health status (HEALTHY, DEGRADED, UNHEALTHY). - message (str): Human-readable status description. - latency_ms (float | None): Query latency in milliseconds, if available. - details (dict[str, Any] | None): Additional diagnostic information - (e.g., active connections, pool statistics). - Example: Creating and using a health check result:: @@ -81,9 +74,16 @@ class HealthCheckResult: """ status: HealthStatus + """Overall health status (HEALTHY, DEGRADED, UNHEALTHY).""" + message: str + """Human-readable status description.""" + latency_ms: float | None = None + """Query latency in milliseconds, if available.""" + details: dict[str, Any] | None = None + """Additional diagnostic information (e.g., active connections, pool statistics).""" @runtime_checkable