deepdoc 1.9.2__tar.gz → 2.0.0__tar.gz

{deepdoc-1.9.2 → deepdoc-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 1.9.2
+Version: 2.0.0
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/__init__.py

@@ -1,3 +1,3 @@
 """DeepDoc — Auto-generate beautiful docs from any codebase."""
 
-__version__ = "1.9.2"
+__version__ = "2.0.0"

deepdoc-2.0.0/deepdoc/changelog_writer.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .persistence_v2 import append_changelog_entry, load_changelog, load_plan, save_plan
+
+
+def record_and_write(
+    repo_root: Path,
+    output_dir: Path,
+    *,
+    commit: str,
+    commit_message: str,
+    commit_date: str,
+    strategy: str,
+    pages_updated: list[str],
+    files_changed: list[str],
+    is_initial: bool = False,
+) -> None:
+    """Append one changelog entry and regenerate whats-changed.mdx."""
+    entry = {
+        "commit": commit[:8],
+        "date": commit_date,
+        "commit_message": commit_message,
+        "strategy": strategy,
+        "pages_updated": pages_updated,
+        "files_changed": files_changed[:20],
+        "is_initial": is_initial,
+    }
+    append_changelog_entry(repo_root, entry)
+    write_whats_changed_page(repo_root, output_dir)
+
+
+def write_whats_changed_page(repo_root: Path, output_dir: Path) -> None:
+    """Write docs/whats-changed.mdx from .deepdoc/changelog.json."""
+    entries = load_changelog(repo_root)
+    mdx = _build_mdx(entries)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "whats-changed.mdx").write_text(mdx, encoding="utf-8")
+    _ensure_in_nav(repo_root)
+
+
+def _build_mdx(entries: list[dict]) -> str:
+    lines = [
+        "---",
+        'title: "What\'s Changed"',
+        'description: "Documentation changes per commit"',
+        "---",
+        "",
+        "# What's Changed",
+        "",
+    ]
+
+    if not entries:
+        lines.append("No changes recorded yet — this is the initial documentation.")
+        return "\n".join(lines)
+
+    lines.append("<Accordions>")
+    for entry in entries:
+        date = entry.get("date", "")
+        msg = entry.get("commit_message", "update")[:80]
+        sha = entry.get("commit", "")
+        pages = entry.get("pages_updated", [])
+        files = entry.get("files_changed", [])
+        is_initial = entry.get("is_initial", False)
+
+        title = f"{date} — {msg} ({sha})"
+        lines.append(f'<Accordion title="{title}">')
+        lines.append("")
+
+        if is_initial:
+            lines.append(f"**{len(pages)} pages generated** — initial documentation run.")
+        else:
+            if pages:
+                page_links = ", ".join(f"[{_slug_to_title(s)}](/{s})" for s in pages)
+                lines.append(f"**{len(pages)} page(s) updated:** {page_links}")
+            else:
+                lines.append("No pages regenerated.")
+
+        if files and not is_initial:
+            file_list = ", ".join(f"`{f}`" for f in files[:10])
+            if len(files) > 10:
+                file_list += f" +{len(files) - 10} more"
+            lines.append("")
+            lines.append(f"**Files changed:** {file_list}")
+
+        lines.append("")
+        lines.append("</Accordion>")
+
+    lines.append("</Accordions>")
+    return "\n".join(lines)
+
+
+def _slug_to_title(slug: str) -> str:
+    return slug.replace("-", " ").title()
+
+
+def _ensure_in_nav(repo_root: Path) -> None:
+    """Add whats-changed to Start Here section of the saved plan if not already there."""
+    plan = load_plan(repo_root)
+    if plan is None or not hasattr(plan, "nav_structure"):
+        return
+    section = plan.nav_structure.setdefault("Start Here", [])
+    if "whats-changed" not in section:
+        section.append("whats-changed")
+    save_plan(plan, repo_root)

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/cli.py

@@ -1200,13 +1200,17 @@ def _warn_if_deprecated_generated_version(cfg: dict, repo_root: Path) -> None:
     if not warning_cfg.get("enabled", True):
         return
 
-    minimum_version = str(warning_cfg.get("minimum_version") or "1.0.0")
     generated_version = _detect_generated_deepdoc_version(
         repo_root, repo_root / str(cfg.get("output_dir", "docs") or "docs")
     )
     if generated_version is None:
         return
-    if _version_tuple(generated_version) >= _version_tuple(minimum_version):
+
+    # Warn when the docs were generated by a different major version of the CLI.
+    # Minor/patch bumps are backwards-compatible — no need to nag.
+    gen_major = _version_tuple(generated_version)[0]
+    cli_major = _version_tuple(__version__)[0]
+    if gen_major >= cli_major:
         return
 
     resolved_root = repo_root.resolve()
@@ -1214,19 +1218,15 @@ def _warn_if_deprecated_generated_version(cfg: dict, repo_root: Path) -> None:
         return
     _DEPRECATED_VERSION_WARNING_REPOS.add(resolved_root)
 
-    upgrade_command = str(
-        warning_cfg.get("upgrade_command")
-        or "python3 -m pip install --upgrade deepdoc"
-    )
     console.print(
         Panel.fit(
-            "[bold yellow]DeepDoc upgrade recommended[/bold yellow]\n\n"
-            f"This repository has generated docs from DeepDoc [bold]{generated_version}[/bold], "
-            f"which is older than the supported baseline [bold]{minimum_version}[/bold].\n"
-            "Upgrade the CLI before generating or updating docs:\n\n"
-            f"[bold]{upgrade_command}[/bold]\n\n"
-            "To change or disable this warning, update "
-            "`compatibility.deprecated_version_warning.*` in `.deepdoc.yaml`.",
+            "[bold yellow]Docs need regeneration[/bold yellow]\n\n"
+            f"Your docs were generated with DeepDoc [bold]{generated_version}[/bold] "
+            f"but the current CLI is [bold]{__version__}[/bold] (different major version).\n"
+            "Run the following to bring them up to date:\n\n"
+            "[bold]deepdoc generate[/bold]\n\n"
+            "To disable this warning: set "
+            "`compatibility.deprecated_version_warning.enabled: false` in `.deepdoc.yaml`.",
             border_style="yellow",
         )
     )

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/generator/generation.py

@@ -1072,6 +1072,7 @@ Re-run `deepdoc generate` to retry.
             "deepdoc_generated_version": DEEPDOC_VERSION,
             "deepdoc_status": status_value,
             "deepdoc_evidence_files": evidence_files[:50],
+            "deepdoc_prereqs": bucket.depends_on,
         }
         return _merge_frontmatter_fields(content, fields)
 

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/generator/post_processors.py

@@ -957,6 +957,10 @@ def repair_mdx_component_blocks(content: str) -> str:
 
         content = pattern.sub(_rewrite, content)
 
+    # Fix Accordion nesting first (inserts missing </Accordion> before </Accordions>)
+    # so the subsequent count-based repair sees balanced tags and doesn't double-add.
+    content = _repair_accordion_nesting(content)
+
     for component in multiline_components:
         open_count = len(re.findall(rf"<{component}(?:\s[^>]*)?>", content))
         close_count = len(re.findall(rf"</{component}>", content))
@@ -968,6 +972,38 @@ def repair_mdx_component_blocks(content: str) -> str:
     return content
 
 
+def _repair_accordion_nesting(content: str) -> str:
+    """Fix Accordion nesting issues emitted by the LLM.
+
+    Two cases handled:
+    1. Missing </Accordion> before </Accordions> — inserts them in the right place.
+    2. Swapped order (</Accordions> then </Accordion>) — strips the orphaned
+       </Accordion> that appears after </Accordions> with no matching open tag.
+    """
+    import re as _re
+
+    def _fix_block(m: re.Match) -> str:
+        block = m.group(0)
+        opens = len(_re.findall(r"<Accordion(?:\s[^>]*)?>", block))
+        closes = len(_re.findall(r"</Accordion>", block))
+        deficit = opens - closes
+        if deficit <= 0:
+            return block
+        return block[:-len("</Accordions>")] + ("</Accordion>\n" * deficit) + "</Accordions>"
+
+    content = re.sub(
+        r"<Accordions(?:\s[^>]*)?>[\s\S]*?</Accordions>",
+        _fix_block,
+        content,
+    )
+
+    # Strip orphaned </Accordion> tags that appear after </Accordions>
+    # (the LLM sometimes emits </Accordions>\n</Accordion> in the wrong order)
+    content = re.sub(r"(</Accordions>)(\s*</Accordion>)+", r"\1", content)
+
+    return content
+
+
 _PROVENANCE_KEYS = frozenset({
     "deepdoc_generated_at",
     "deepdoc_generated_commit",

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/persistence_v2.py

@@ -37,6 +37,8 @@ LEDGER_FILE = "ledger.json"
 FILE_MAP_FILE = "file_map.json"
 STATE_FILE = "state.json"
 SYNC_RECEIPT_FILE = "sync_receipt.json"
+CHANGELOG_FILE = "changelog.json"
+CHANGELOG_MAX_ENTRIES = 50
 ENGINE_FINGERPRINT = "routes_repo_resolution_v2_trimmed_scope"
 
 # Legacy top-level files (kept for backwards-compat)
@@ -108,6 +110,31 @@ def load_sync_state(repo_root: Path) -> dict[str, Any] | None:
         return None
 
 
+def append_changelog_entry(repo_root: Path, entry: dict[str, Any]) -> None:
+    """Append one entry to .deepdoc/changelog.json, capped at CHANGELOG_MAX_ENTRIES."""
+    path = _state_dir(repo_root) / CHANGELOG_FILE
+    entries: list[dict[str, Any]] = []
+    if path.exists():
+        try:
+            entries = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            entries = []
+    entries.insert(0, entry)
+    entries = entries[:CHANGELOG_MAX_ENTRIES]
+    path.write_text(json.dumps(entries, indent=2), encoding="utf-8")
+
+
+def load_changelog(repo_root: Path) -> list[dict[str, Any]]:
+    """Read .deepdoc/changelog.json. Returns empty list if not present or corrupt."""
+    path = _state_dir(repo_root) / CHANGELOG_FILE
+    if not path.exists():
+        return []
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+
+
 def save_sync_receipt(repo_root: Path, receipt: dict[str, Any]) -> None:
     """Write a top-level receipt for the latest generate/update sync run."""
     path = _state_dir(repo_root) / SYNC_RECEIPT_FILE

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/pipeline_v2.py

@@ -51,8 +51,10 @@ from .openapi import (
     parse_openapi_spec,
     spec_to_context_string,
 )
+from .changelog_writer import record_and_write as _record_changelog
 from .persistence_v2 import (
     cleanup_stale_generated_files,
+    load_changelog,
     load_generation_ledger,
     prune_generation_ledger,
     save_all,
@@ -112,6 +114,36 @@ def _endpoint_ref_slug(method: str, path: str) -> str:
     return f"{method.lower()}-{path_slug}"
 
 
+def _spec_base_path(spec: dict) -> str:
+    """Return the base path from the first server URL, e.g. '/api/v2'."""
+    from urllib.parse import urlparse
+    if "openapi" in spec:
+        servers = spec.get("servers", [])
+        if servers:
+            url = str(servers[0].get("url", "") or "").strip()
+            parsed = urlparse(url)
+            base = parsed.path if (parsed.scheme or parsed.netloc) else url
+            return base.rstrip("/")
+    elif "swagger" in spec:
+        return spec.get("basePath", "").rstrip("/")
+    return ""
+
+
+def _write_spec(dest: Path, spec: dict) -> None:
+    """Write spec dict to dest as YAML or JSON depending on suffix."""
+    if dest.suffix == ".json":
+        dest.write_text(json.dumps(spec, indent=2) + "\n", encoding="utf-8")
+    else:
+        try:
+            import yaml
+            dest.write_text(
+                yaml.dump(spec, allow_unicode=True, sort_keys=False, default_flow_style=False),
+                encoding="utf-8",
+            )
+        except ImportError:
+            dest.write_text(json.dumps(spec, indent=2) + "\n", encoding="utf-8")
+
+
 def stage_openapi_assets(
     repo_root: Path, openapi_paths: list[str] | None = None
 ) -> bool:
@@ -136,7 +168,6 @@ def stage_openapi_assets(
 
         spec_name = Path(spec_rel_path).name
         staged_spec = site_openapi_dir / spec_name
-        shutil.copy2(spec_src, staged_spec)
 
         spec = parse_openapi_spec(spec_src)
         if not spec:
@@ -145,6 +176,20 @@ def stage_openapi_assets(
             )
             return False
 
+        # Bake the server base path into each path key so Fumadocs can do a
+        # direct dict lookup (it does not prepend the server URL itself).
+        base_path = _spec_base_path(spec)
+        if base_path and not any(
+            k.startswith(base_path) for k in spec.get("paths", {})
+        ):
+            spec = {
+                **spec,
+                "paths": {base_path + k: v for k, v in spec["paths"].items()},
+                "servers": [{"url": "/"}],
+            }
+
+        _write_spec(staged_spec, spec)
+
         endpoints = extract_endpoints_from_spec(spec)
         manifest: list[dict[str, str]] = []
         for ep in endpoints:
@@ -381,6 +426,19 @@ class PipelineV2:
                     "replanned": True,
                 },
             )
+            changelog_exists = bool(load_changelog(self.repo_root))
+            _commit_obj = _repo.head.commit
+            _record_changelog(
+                self.repo_root,
+                self.output_dir,
+                commit=head_sha,
+                commit_message=_commit_obj.message.strip().splitlines()[0],
+                commit_date=_commit_obj.committed_datetime.strftime("%Y-%m-%d"),
+                strategy="full_generate",
+                pages_updated=[b.slug for b in plan.buckets],
+                files_changed=[],
+                is_initial=not changelog_exists,
+            )
         except Exception:
             pass  # Not a git repo or detached HEAD — skip silently
 

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/planner/bucket_injection.py

@@ -405,6 +405,64 @@ _GENERIC_PLACEHOLDER_SECTIONS = {
     "pages",
 }
 
+_BACKEND_INTEGRATION_TOKENS = {
+    "cdn",
+    "clickpost",
+    "express",
+    "gateway",
+    "integration",
+    "provider",
+    "third",
+    "vinculum",
+    "warehouse",
+    "wms",
+}
+
+_BACKEND_OPERATION_TOKENS = {
+    "config",
+    "cron",
+    "debug",
+    "health",
+    "log",
+    "logger",
+    "logging",
+    "metric",
+    "monitor",
+    "observability",
+    "scheduler",
+    "utility",
+    "utilities",
+}
+
+_BACKEND_RUNTIME_TOKENS = {
+    "agenda",
+    "async",
+    "background",
+    "celery",
+    "command",
+    "consumer",
+    "cron",
+    "django",
+    "job",
+    "queue",
+    "scheduler",
+    "signal",
+    "task",
+    "worker",
+}
+
+_PATH_SECTION_PREFIXES = (
+    "new-src-",
+    "src-",
+    "app-",
+    "lib-",
+    "packages-",
+    "services-",
+    "controllers-",
+    "middlewares-",
+    "utils-",
+)
+
 
 def _canonical_section_for_bucket(bucket: DocBucket, primary_type: str) -> str:
     # Supporting-tier buckets always get re-sectioned (Testing, CI/CD, etc.) regardless
@@ -412,7 +470,12 @@ def _canonical_section_for_bucket(bucket: DocBucket, primary_type: str) -> str:
     # domain-specific section name rather than overriding with a generic canonical one.
     if bucket.publication_tier != "supporting":
         existing = (bucket.section or "").strip()
-        if existing and existing.lower() not in _GENERIC_PLACEHOLDER_SECTIONS:
+        if (
+            existing
+            and existing.lower() not in _GENERIC_PLACEHOLDER_SECTIONS
+            and not _looks_like_path_slug_section(existing)
+            and not _is_backend_placeholder_section(existing, primary_type)
+        ):
             return existing
 
     title_tokens = _bucket_semantic_tokens(bucket)
@@ -570,23 +633,25 @@ def _canonical_section_for_bucket(bucket: DocBucket, primary_type: str) -> str:
             "is_endpoint_family"
         ) or bucket.generation_hints.get("is_endpoint_ref"):
             return "API Reference"
-        if any(
-            token in title_tokens
-            for token in {"middleware", "auth", "route", "controller", "handler"}
-        ):
-            return "Runtime & Frameworks"
         if any(
             token in title_tokens
             for token in {"model", "schema", "migration", "database"}
         ):
             return "Data Layer"
-        if any(
-            token in title_tokens for token in {"provider", "gateway", "integration"}
+        if bucket.bucket_type in {"runtime", "runtime-group"} or any(
+            token in title_tokens for token in _BACKEND_RUNTIME_TOKENS
         ):
-            return "Integrations"
-        if any(token in title_tokens for token in {"queue", "task", "worker", "sync"}):
             return "Background Jobs"
-        return "Subsystems"
+        if any(token in title_tokens for token in _BACKEND_INTEGRATION_TOKENS):
+            return "Integrations"
+        if any(token in title_tokens for token in _BACKEND_OPERATION_TOKENS):
+            return "Operations"
+        if any(
+            token in title_tokens
+            for token in {"middleware", "auth", "route", "controller", "handler"}
+        ):
+            return "Supporting Infrastructure"
+        return "Core Workflows"
     if bucket.generation_hints.get("is_introduction_page"):
         return "Overview"
     if bucket.generation_hints.get("is_endpoint_family") or bucket.generation_hints.get(
@@ -605,3 +670,30 @@ def _canonical_section_for_bucket(bucket: DocBucket, primary_type: str) -> str:
     ):
         return "Operations"
     return "Architecture"
+
+
+def _looks_like_path_slug_section(section: str) -> bool:
+    value = (section or "").strip()
+    if not value:
+        return False
+    if " > " in value or "/" in value or "\\" in value:
+        return False
+    lower = value.lower()
+    if lower != value or "-" not in lower:
+        return False
+    if lower.endswith(("-ts", "-js", "-tsx", "-jsx", "-py", "-php", "-go")):
+        return True
+    return lower.startswith(_PATH_SECTION_PREFIXES) and lower.count("-") >= 2
+
+
+def _is_backend_placeholder_section(section: str, primary_type: str) -> bool:
+    if primary_type not in {"backend_service", "backend_api", "falcon_backend"}:
+        return False
+    return section.strip().lower() in {
+        "architecture",
+        "core",
+        "features",
+        "runtime & frameworks",
+        "services",
+        "subsystems",
+    }

{deepdoc-1.9.2 → deepdoc-2.0.0}/deepdoc/planner/nav_shaping.py

@@ -2,6 +2,18 @@ from .common import *
 from .bucket_refinement import _bucket_semantic_tokens
 from .bucket_injection import _canonical_section_for_bucket
 
+_PATH_SECTION_PREFIXES = (
+    "new-src-",
+    "src-",
+    "app-",
+    "lib-",
+    "packages-",
+    "services-",
+    "controllers-",
+    "middlewares-",
+    "utils-",
+)
+
 
 def _shape_plan_nav(
     plan: DocPlan,
@@ -24,7 +36,7 @@ def _shape_plan_nav(
             continue
 
         hints = bucket.generation_hints or {}
-        if not hints.get("preserve_section"):
+        if not hints.get("preserve_section") or _is_path_slug_section(bucket.section):
             bucket.section = _canonical_section_for_bucket(bucket, primary)
 
         bucket.section = _normalize_nav_section(bucket.section, primary)
@@ -150,10 +162,27 @@ def _normalize_nav_section(section: str, primary: str) -> str:
     }.get(top, top)
 
     if sep:
+        if rest.strip() == top:
+            return top
         return f"{top} > {rest}"
     return top
 
 
+def _is_path_slug_section(section: str) -> bool:
+    """Return True when the section looks like a file path cluster id."""
+    value = (section or "").strip()
+    if not value:
+        return False
+    if " > " in value or "/" in value or "\\" in value:
+        return False
+    lower = value.lower()
+    if lower != value or "-" not in lower:
+        return False
+    if lower.endswith(("-ts", "-js", "-tsx", "-jsx", "-py", "-php", "-go")):
+        return True
+    return lower.startswith(_PATH_SECTION_PREFIXES) and lower.count("-") >= 2
+
+
 def _build_endpoint_reference_nav(buckets: list[DocBucket]) -> dict[str, list[str]]:
     families = [
         bucket
@@ -283,6 +312,27 @@ def _section_sort_key(
         rank = _RT_ORDER.index(top) if top in _RT_ORDER else 10
         return (rank, section_order.get(section, 999), section)
 
+    if primary in {"backend_service", "backend_api", "falcon_backend"}:
+        _BACKEND_ORDER = [
+            "Start Here",
+            "Overview",
+            "Core Workflows",
+            "API Reference",
+            "Data Model",
+            "Background Jobs",
+            "Integrations",
+            "Operations",
+            "Runtime & Frameworks",
+            "Supporting Infrastructure",
+            "Design & Notes",
+            "Testing",
+            "CI/CD and Release",
+            "Supporting Material",
+        ]
+        rank = _BACKEND_ORDER.index(top) if top in _BACKEND_ORDER else 8
+        child_rank = 0 if section == top else 1
+        return (rank, child_rank, section_order.get(section, 999), section)
+
     _FIRST = {"Start Here": 0, "Overview": 1, "Getting Started": 2}
     _LAST = {
         "Supporting Infrastructure": 55,