svc-infra 0.1.614__tar.gz → 0.1.616__tar.gz

{svc_infra-0.1.614 → svc_infra-0.1.616}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.614
+Version: 0.1.616
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

{svc_infra-0.1.614 → svc_infra-0.1.616}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.614"
+version = "0.1.616"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"
@@ -12,7 +12,8 @@ include = [
     "src/svc_infra/db/templates/**/*",
     "src/svc_infra/obs/templates/**/*",
     "src/svc_infra/obs/grafana/templates/**/*",
-    "src/svc_infra/obs/grafana/dashboards/**/*"
+    "src/svc_infra/obs/grafana/dashboards/**/*",
+    "src/svc_infra/bundled_docs/**/*"
 ]
 
 classifiers = [

svc_infra-0.1.616/src/svc_infra/bundled_docs/README.md

@@ -0,0 +1,5 @@
+# Bundled Docs
+
+This directory contains a minimal set of Markdown files that the `svc-infra docs` CLI can fall back to when the project running the CLI doesn't have a local `docs/` directory.
+
+You can add more topics here as needed; each `*.md` file becomes a topic named after its stem (e.g., `getting-started.md` -> `getting-started`).

svc_infra-0.1.616/src/svc_infra/bundled_docs/__init__.py

@@ -0,0 +1 @@
+# Bundled docs package for zip-safe importlib.resources access

svc_infra-0.1.616/src/svc_infra/bundled_docs/getting-started.md

@@ -0,0 +1,6 @@
+# Getting Started
+
+Welcome to svc-infra docs. Use `svc-infra docs list` to see topics.
+
+- This content is bundled with the package.
+- If your project doesn't have a local `docs/` folder, you'll still see this.

{svc_infra-0.1.614 → svc_infra-0.1.616}/src/svc_infra/cli/__init__.py

@@ -6,6 +6,7 @@ from svc_infra.cli.cmds import (
     _HELP,
     jobs_app,
     register_alembic,
+    register_docs,
     register_dx,
     register_mongo,
     register_mongo_scaffold,
@@ -40,6 +41,9 @@ app.add_typer(jobs_app, name="jobs")
 # -- sdk commands ---
 register_sdk(app)
 
+# -- docs commands ---
+register_docs(app)
+
 
 def main():
     app()

{svc_infra-0.1.614 → svc_infra-0.1.616}/src/svc_infra/cli/cmds/__init__.py

@@ -5,6 +5,7 @@ from svc_infra.cli.cmds.db.nosql.mongo.mongo_scaffold_cmds import (
 from svc_infra.cli.cmds.db.sql.alembic_cmds import register as register_alembic
 from svc_infra.cli.cmds.db.sql.sql_export_cmds import register as register_sql_export
 from svc_infra.cli.cmds.db.sql.sql_scaffold_cmds import register as register_sql_scaffold
+from svc_infra.cli.cmds.docs.docs_cmds import register as register_docs
 from svc_infra.cli.cmds.dx import register_dx
 from svc_infra.cli.cmds.jobs.jobs_cmds import app as jobs_app
 from svc_infra.cli.cmds.obs.obs_cmds import register as register_obs
@@ -22,5 +23,6 @@ __all__ = [
     "jobs_app",
     "register_sdk",
     "register_dx",
+    "register_docs",
     "_HELP",
 ]

svc_infra-0.1.616/src/svc_infra/cli/cmds/docs/docs_cmds.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict, List
+
+import click
+import typer
+from typer.core import TyperGroup
+
+from svc_infra.app.root import resolve_project_root
+
+
+def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
+    topics: Dict[str, Path] = {}
+    if docs_dir.exists() and docs_dir.is_dir():
+        for p in sorted(docs_dir.glob("*.md")):
+            if p.is_file():
+                topics[p.stem.replace(" ", "-")] = p
+    return topics
+
+
+def _discover_pkg_topics() -> Dict[str, object]:
+    topics: Dict[str, object] = {}
+    try:
+        import importlib.resources as ir
+
+        pkg_docs = ir.files("svc_infra.bundled_docs")
+        for res in pkg_docs.iterdir():
+            if res.name.endswith(".md"):
+                topics[Path(res.name).stem.replace(" ", "-")] = res
+    except Exception:
+        pass
+    return topics
+
+
+def _resolve_docs_dir(ctx: click.Context) -> Path | None:
+    # CLI option takes precedence; walk up parent contexts because Typer
+    # executes subcommands in child contexts that do not inherit params.
+    current: click.Context | None = ctx
+    while current is not None:
+        docs_dir = (current.params or {}).get("docs_dir")
+        if docs_dir:
+            path = docs_dir if isinstance(docs_dir, Path) else Path(docs_dir)
+            path = path.expanduser()
+            if path.exists():
+                return path
+        current = current.parent
+    # Env var next
+    env_dir = os.getenv("SVC_INFRA_DOCS_DIR")
+    if env_dir:
+        p = Path(env_dir).expanduser()
+        if p.exists():
+            return p
+    # Project docs
+    root = resolve_project_root()
+    proj_docs = root / "docs"
+    if proj_docs.exists():
+        return proj_docs
+    return None
+
+
+class DocsGroup(TyperGroup):
+    def list_commands(self, ctx: click.Context) -> List[str]:
+        names: List[str] = list(super().list_commands(ctx) or [])
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        pkg = _discover_pkg_topics() if not fs else {}
+        names.extend(fs.keys())
+        names.extend(pkg.keys())
+        # Deduplicate and sort
+        uniq = sorted({*names})
+        return uniq
+
+    def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
+        # Built-ins first (e.g., list)
+        cmd = super().get_command(ctx, name)
+        if cmd is not None:
+            return cmd
+
+        # Dynamic topic resolution
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if name in fs:
+            file_path = fs[name]
+
+            @click.command(name=name)
+            def _show_fs() -> None:
+                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
+
+            return _show_fs
+
+        if not fs:
+            pkg = _discover_pkg_topics()
+            if name in pkg:
+                res = pkg[name]
+
+                @click.command(name=name)
+                def _show_pkg() -> None:
+                    try:
+                        import importlib.resources as ir
+
+                        content = getattr(res, "read_text", None)
+                        if callable(content):
+                            text = content(encoding="utf-8", errors="replace")
+                        else:
+                            with ir.as_file(res) as p:
+                                text = Path(p).read_text(encoding="utf-8", errors="replace")
+                        click.echo(text)
+                    except Exception as e:  # pragma: no cover
+                        raise click.ClickException(f"Failed to load bundled doc: {e}")
+
+                return _show_pkg
+
+        return None
+
+
+def register(app: typer.Typer) -> None:
+    """Register the `docs` command group with dynamic topic subcommands."""
+
+    docs_app = typer.Typer(no_args_is_help=True, add_completion=False, cls=DocsGroup)
+
+    @docs_app.callback(invoke_without_command=True)
+    def _docs_options(
+        docs_dir: Path | None = typer.Option(
+            None,
+            "--docs-dir",
+            help="Path to a docs directory to read from (overrides env/project root)",
+        ),
+        topic: str | None = typer.Option(None, "--topic", help="Topic to show directly"),
+    ) -> None:
+        """Support --docs-dir and --topic at group level."""
+        if topic:
+            ctx = click.get_current_context()
+            dir_to_use = _resolve_docs_dir(ctx)
+            fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+            if topic in fs:
+                typer.echo(fs[topic].read_text(encoding="utf-8", errors="replace"))
+                raise typer.Exit(code=0)
+            if not fs:
+                pkg = _discover_pkg_topics()
+                if topic in pkg:
+                    try:
+                        import importlib.resources as ir
+
+                        res = pkg[topic]
+                        content = getattr(res, "read_text", None)
+                        if callable(content):
+                            text = content(encoding="utf-8", errors="replace")
+                        else:
+                            with ir.as_file(res) as p:
+                                text = Path(p).read_text(encoding="utf-8", errors="replace")
+                        typer.echo(text)
+                        raise typer.Exit(code=0)
+                    except Exception as e:  # pragma: no cover
+                        raise typer.BadParameter(f"Failed to load bundled topic '{topic}': {e}")
+            raise typer.BadParameter(f"Unknown topic: {topic}")
+
+    @docs_app.command("list", help="List available documentation topics")
+    def list_topics() -> None:
+        ctx = click.get_current_context()
+        root = resolve_project_root()
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        pkg = _discover_pkg_topics() if not fs else {}
+        for name, path in fs.items():
+            try:
+                rel = path.relative_to(root)
+                typer.echo(f"{name}\t{rel}")
+            except Exception:
+                typer.echo(f"{name}\t{path}")
+        for name in sorted(pkg.keys()):
+            typer.echo(f"{name}\t(bundled)")
+
+    # Also support a generic "show" command
+    @docs_app.command("show", help="Show docs for a topic (alternative to dynamic subcommand)")
+    def show(topic: str) -> None:
+        ctx = click.get_current_context()
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if topic in fs:
+            typer.echo(fs[topic].read_text(encoding="utf-8", errors="replace"))
+            return
+        if not fs:
+            pkg = _discover_pkg_topics()
+            if topic in pkg:
+                try:
+                    import importlib.resources as ir
+
+                    res = pkg[topic]
+                    content = getattr(res, "read_text", None)
+                    if callable(content):
+                        text = content(encoding="utf-8", errors="replace")
+                    else:
+                        with ir.as_file(res) as p:
+                            text = Path(p).read_text(encoding="utf-8", errors="replace")
+                    typer.echo(text)
+                    return
+                except Exception as e:  # pragma: no cover
+                    raise typer.BadParameter(f"Failed to load bundled topic '{topic}': {e}")
+        raise typer.BadParameter(f"Unknown topic: {topic}")
+
+    app.add_typer(docs_app, name="docs")