sphinx-mkdocs-migrate 0.0.1.dev0__py3-none-any.whl

sphinx_mkdocs_migrate/planner/toctree.py

@@ -0,0 +1,158 @@
+"""Semantic navigation and Sphinx toctree layout planner."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Optional, Set
+from ..analyzer.models import NavigationItem
+
+
+def resolve_navigation_docnames(
+    nav_entries: List[NavigationItem],
+    all_files: List[Path],
+    docs_dir: Path,
+    project_root: Optional[Path] = None,
+    generated_targets: Optional[Set[str]] = None,
+) -> List[str]:
+    """Resolve ordered Sphinx document names from MkDocs navigation items and file discoveries."""
+    ordered_docnames: List[str] = []
+    generated_targets = generated_targets or set()
+
+    def resolve_path(raw_path: str) -> Optional[str]:
+        """Resolve a page or a literate-nav wildcard to a Sphinx docname."""
+        clean_p = raw_path.strip()
+        if clean_p.startswith("http"):
+            return None
+
+        if "|" in clean_p:
+            wildcard_parts = [
+                part.strip() for part in clean_p.split("|") if "*" in part
+            ]
+            if wildcard_parts:
+                wildcard = wildcard_parts[0]
+                base_dir = wildcard.replace("/*", "").replace("*", "").strip("/")
+                index_doc = f"{base_dir}/index" if base_dir else "index"
+                if (
+                    docs_dir / f"{index_doc}.md"
+                ).exists() or index_doc in generated_targets:
+                    return index_doc
+                target_dir = docs_dir / base_dir
+                if target_dir.is_dir():
+                    # No landing page exists. Keep legacy fallback.
+                    return None
+                return None
+            clean_p = next(
+                (part.strip() for part in clean_p.split("|") if part.strip() != "..."),
+                "",
+            )
+
+        clean_p = clean_p.split("#", 1)[0].replace("\\", "/").strip("/")
+        if clean_p.endswith(".md"):
+            clean_p = clean_p[:-3]
+        if not clean_p:
+            return None
+        if (docs_dir / clean_p / "index.md").exists():
+            return f"{clean_p}/index"
+        if clean_p in generated_targets:
+            return clean_p
+        if f"{clean_p}/index" in generated_targets:
+            return f"{clean_p}/index"
+        return clean_p
+
+    def add_doc(title: Optional[str], docname: str) -> None:
+        if docname == "index":
+            entry = f"{title or 'Home'} <self>"
+        elif title and title.lower() != Path(docname).stem.lower():
+            entry = f"{title} <{docname}>"
+        else:
+            entry = docname
+        if entry not in ordered_docnames:
+            ordered_docnames.append(entry)
+
+    def section_landing(item: NavigationItem) -> Optional[str]:
+        """Find the page that represents a section in the target tree."""
+        if item.path:
+            return resolve_path(item.path)
+        for child in item.children:
+            candidate = section_landing(child)
+            if candidate:
+                return candidate
+        return None
+
+    def expand_wildcard(raw_path: str) -> None:
+        """Compatibility fallback for a wildcard with no index/landing page."""
+        wildcard = next(
+            (part.strip() for part in raw_path.split("|") if "*" in part), ""
+        )
+        base_dir = wildcard.replace("/*", "").replace("*", "").strip("/")
+        target_dir = docs_dir / base_dir
+        if not target_dir.is_dir():
+            return
+        for path in sorted(target_dir.rglob("*.md")):
+            if path.name != "index.md":
+                add_doc(None, path.relative_to(docs_dir).with_suffix("").as_posix())
+
+    def collect_nav_docs(items: List[NavigationItem]):
+        for item in items:
+            target = resolve_path(item.path) if item.path else None
+            if target:
+                add_doc(item.title, target)
+                continue
+            if item.path and "*" in item.path:
+                expand_wildcard(item.path)
+                continue
+            if item.children:
+                landing = section_landing(item)
+                if landing:
+                    add_doc(item.title, landing)
+                else:
+                    # A section without a landing document cannot be nested
+                    # in a Sphinx toctree, so retain its explicitly listed pages.
+                    collect_nav_docs(item.children)
+
+    if nav_entries:
+        collect_nav_docs(nav_entries)
+    else:
+        # Fallback if no nav defined: preserve discovered documents deterministically
+        for f in all_files:
+            rel = f.relative_to(docs_dir)
+            if rel.name != "index.md":
+                docname = rel.with_suffix("").as_posix()
+                if docname not in ordered_docnames:
+                    ordered_docnames.append(docname)
+
+    return ordered_docnames
+
+
+def build_semantic_toctree(
+    nav_entries: List[NavigationItem],
+    all_files: List[Path],
+    docs_dir: Path,
+    project_root: Optional[Path] = None,
+    generated_targets: Optional[Set[str]] = None,
+    hidden: bool = True,
+    maxdepth: int = 2,
+) -> Optional[str]:
+    """Generate the root toctree directive block without flattening section landing pages."""
+    ordered_docnames = resolve_navigation_docnames(
+        nav_entries=nav_entries,
+        all_files=all_files,
+        docs_dir=docs_dir,
+        project_root=project_root,
+        generated_targets=generated_targets,
+    )
+
+    if not ordered_docnames:
+        return None
+
+    lines = [
+        "```{toctree}",
+    ]
+    if hidden:
+        lines.append(":hidden:")
+    if maxdepth > 0:
+        lines.append(f":maxdepth: {maxdepth}")
+    lines.append("")
+    for docname in ordered_docnames:
+        lines.append(docname)
+    lines.append("```")
+    return "\n".join(lines)

sphinx_mkdocs_migrate/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

sphinx_mkdocs_migrate/rules/catalog.py

@@ -0,0 +1,154 @@
+"""Comprehensive catalog of declarative migration rules with requirements and preservation constraints."""
+
+from typing import List, Dict
+from ..parsing.markdown_ir import NodeKind
+from ..analyzer.models import Classification
+from .models import MigrationRule, MigrationTarget, RuleKind
+
+SUPPORTED_MYST_ADMONITIONS: Dict[str, str] = {
+    "note": "note",
+    "warning": "warning",
+    "tip": "tip",
+    "info": "note",
+    "important": "important",
+    "caution": "caution",
+    "danger": "danger",
+    "seealso": "seealso",
+    "example": "admonition",
+    "quote": "admonition",
+    "abstract": "admonition",
+    "bug": "admonition",
+    "question": "admonition",
+    "check": "admonition",
+    "fail": "admonition",
+    "success": "admonition",
+}
+
+DEFAULT_RULES: List[MigrationRule] = [
+    # 1. Admonitions
+    MigrationRule(
+        rule_id="rule.admonition.myst",
+        source_kind=NodeKind.ADMONITION,
+        rule_kind=RuleKind.DETERMINISTIC,
+        classification=Classification.TRANSFORM,
+        target=MigrationTarget(
+            framework="MyST",
+            directive_name="note",
+            required_extensions=["myst_parser"],
+            required_py_packages=["myst-parser>=2.0.0"],
+        ),
+        preserves=["title", "body", "nesting", "admonition_type"],
+        changes=["syntax", "fence_delimiters"],
+        conditions={"type_map": SUPPORTED_MYST_ADMONITIONS},
+        manual_if=["unsupported_custom_admonition_type"],
+        description="Transforms MkDocs '!!! type' admonitions into MyST '{type}' or generic '{admonition}' directives.",
+    ),
+    # 2. Content Tabs
+    MigrationRule(
+        rule_id="rule.tabs.sphinx_design",
+        source_kind=NodeKind.TAB_SET,
+        rule_kind=RuleKind.EXTENSION_DEPENDENT,
+        classification=Classification.TRANSFORM,
+        target=MigrationTarget(
+            framework="sphinx-design",
+            directive_name="tab-set",
+            required_extensions=["sphinx_design"],
+            required_py_packages=["sphinx-design>=0.5.0"],
+        ),
+        preserves=["tab_titles", "child_contents", "nesting"],
+        changes=["syntax", "container_delimiters"],
+        conditions={"has_tab_items": True},
+        manual_if=[],
+        description="Transforms PyMdown '=== \"Title\"' content tabs into sphinx-design '{tab-set}' and '{tab-item}' directives.",
+    ),
+    # 3. Details / Dropdowns
+    MigrationRule(
+        rule_id="rule.details.sphinx_design",
+        source_kind=NodeKind.DETAILS_DROPDOWN,
+        rule_kind=RuleKind.EXTENSION_DEPENDENT,
+        classification=Classification.TRANSFORM,
+        target=MigrationTarget(
+            framework="sphinx-design",
+            directive_name="dropdown",
+            required_extensions=["sphinx_design"],
+            required_py_packages=["sphinx-design>=0.5.0"],
+        ),
+        preserves=["title", "open_state", "body", "nesting"],
+        changes=["syntax", "container_delimiters"],
+        conditions={},
+        manual_if=[],
+        description="Transforms PyMdown '???+ note \"Title\"' collapsible details into sphinx-design '{dropdown}' directives.",
+    ),
+    # 4. mkdocstrings / mkautodoc API Directives
+    MigrationRule(
+        rule_id="rule.api.autodoc",
+        source_kind=NodeKind.API_DIRECTIVE,
+        rule_kind=RuleKind.DETERMINISTIC,
+        classification=Classification.MANUAL,
+        target=MigrationTarget(
+            framework="sphinx.ext.autodoc",
+            directive_name="autoclass",
+            required_extensions=["sphinx.ext.autodoc", "sphinx.ext.napoleon"],
+            required_py_packages=["Sphinx>=7.0.0"],
+        ),
+        preserves=["symbol_path"],
+        changes=["directive_syntax"],
+        conditions={"symbol_format": "dotted_path"},
+        manual_if=["symbol_kind_unknown", "complex_filter_options"],
+        description="Maps '::: symbol.path' to appropriate Sphinx autodoc directives with options.",
+    ),
+    # 5. Snippet Includes
+    MigrationRule(
+        rule_id="rule.snippet.literalinclude",
+        source_kind=NodeKind.SNIPPET_INCLUDE,
+        rule_kind=RuleKind.DETERMINISTIC,
+        classification=Classification.TRANSFORM,
+        target=MigrationTarget(
+            framework="MyST",
+            directive_name="literalinclude",
+            required_extensions=["myst_parser"],
+            required_py_packages=["myst-parser>=2.0.0"],
+        ),
+        preserves=["filepath"],
+        changes=["include_syntax", "relative_root_resolution"],
+        conditions={"filepath_specified": True},
+        manual_if=["missing_target_file"],
+        description="Transforms PyMdown '--8<-- \"path\"' snippet inclusions to MyST/Sphinx '{literalinclude}' or '{include}'.",
+    ),
+    # 6. Mermaid Diagrams
+    MigrationRule(
+        rule_id="rule.mermaid.sphinxcontrib",
+        source_kind=NodeKind.MERMAID_DIAGRAM,
+        rule_kind=RuleKind.EXTENSION_DEPENDENT,
+        classification=Classification.TRANSFORM,
+        target=MigrationTarget(
+            framework="sphinxcontrib-mermaid",
+            directive_name="mermaid",
+            required_extensions=["sphinxcontrib.mermaid"],
+            required_py_packages=["sphinxcontrib-mermaid>=0.9.0"],
+        ),
+        preserves=["diagram_source", "line_mapping"],
+        changes=["fence_name_to_directive"],
+        conditions={"info_string": "mermaid"},
+        manual_if=[],
+        description="Maps '```mermaid' fenced code blocks to sphinxcontrib-mermaid '{mermaid}' directives.",
+    ),
+    # 7. Document Links
+    MigrationRule(
+        rule_id="rule.link.myst_ref",
+        source_kind=NodeKind.LINK_REF,
+        rule_kind=RuleKind.DETERMINISTIC,
+        classification=Classification.PRESERVE,
+        target=MigrationTarget(
+            framework="MyST",
+            directive_name="doc_or_ref",
+            required_extensions=["myst_parser"],
+            required_py_packages=["myst-parser>=2.0.0"],
+        ),
+        preserves=["link_text", "target_url"],
+        changes=["relative_md_extension_resolution"],
+        conditions={},
+        manual_if=["unresolved_internal_reference"],
+        description="Preserves standard links and evaluates relative markdown links for cross-document reference resolution.",
+    ),
+]

sphinx_mkdocs_migrate/rules/engine.py

@@ -0,0 +1,94 @@
+"""Generic declarative rule engine for evaluating DocumentIR trees without procedural construct branching."""
+
+import hashlib
+from typing import List, Dict, Optional
+from ..parsing.markdown_ir import BaseIRNode, NodeKind, DocumentIR
+from .models import MigrationRule, RuleEvaluation, MigrationAction
+from .catalog import DEFAULT_RULES
+
+
+class MigrationRuleEngine:
+    """Evaluates DocumentIR nodes purely by interpreting declarative MigrationRule contracts."""
+
+    def __init__(self, custom_rules: Optional[List[MigrationRule]] = None):
+        self.rules: List[MigrationRule] = (
+            custom_rules if custom_rules is not None else list(DEFAULT_RULES)
+        )
+        self._rules_by_kind: Dict[NodeKind, List[MigrationRule]] = {}
+        for rule in self.rules:
+            self._rules_by_kind.setdefault(rule.source_kind, []).append(rule)
+
+    def evaluate_node(self, node: BaseIRNode) -> Optional[RuleEvaluation]:
+        """Generic evaluation: finds matching rules for node kind and delegates to rule contract."""
+        matching_rules = self._rules_by_kind.get(node.kind, [])
+        for rule in matching_rules:
+            if rule.matches(node):
+                return rule.evaluate(node)
+        return None
+
+    def evaluate_document(self, doc_ir: DocumentIR) -> List[RuleEvaluation]:
+        """Evaluates all nodes across a DocumentIR tree and aggregates rule evaluations."""
+        evaluations: List[RuleEvaluation] = []
+        for node in doc_ir.walk():
+            res = self.evaluate_node(node)
+            if res is not None:
+                evaluations.append(res)
+        return evaluations
+
+    def create_actions(
+        self, doc_ir: DocumentIR, raw_lines: Optional[List[str]] = None
+    ) -> List[MigrationAction]:
+        """Generates normalized MigrationAction items with stable source-span IDs and fingerprints."""
+        actions: List[MigrationAction] = []
+
+        # Helper to compute exact source span text
+        def get_span_fingerprint(start_l: int, end_l: int) -> str:
+            if raw_lines and 1 <= start_l <= len(raw_lines):
+                end_idx = min(end_l, len(raw_lines))
+                span_text = "\n".join(raw_lines[start_l - 1 : end_idx])
+                return hashlib.sha256(span_text.encode("utf-8")).hexdigest()[:16]
+            return ""
+
+        for node in doc_ir.nodes:
+            # We evaluate actions on nodes
+            self._collect_actions(node, doc_ir.file_path, get_span_fingerprint, actions)
+        return actions
+
+    def _collect_actions(
+        self,
+        node: BaseIRNode,
+        file_path: str,
+        fp_helper,
+        actions: List[MigrationAction],
+    ):
+        evaluation = self.evaluate_node(node)
+        if evaluation is not None:
+            stable_span_key = (
+                f"{file_path}:{node.start_line}-{node.end_line}:{evaluation.rule_id}"
+            )
+            action_id = f"act_{hashlib.sha256(stable_span_key.encode('utf-8')).hexdigest()[:12]}"
+
+            target_directive = (
+                evaluation.target.directive_name if evaluation.target else None
+            )
+            action = MigrationAction(
+                action_id=action_id,
+                rule_id=evaluation.rule_id,
+                source_file=file_path,
+                start_line=node.start_line,
+                end_line=node.end_line,
+                classification=evaluation.classification,
+                source_kind=node.kind,
+                source_span_fingerprint=fp_helper(node.start_line, node.end_line),
+                target_directive=target_directive,
+                required_extensions=evaluation.required_extensions,
+                required_packages=evaluation.required_packages,
+                preserves=evaluation.preserved_attributes,
+                manual_instruction=evaluation.action_item,
+                description=evaluation.rationale,
+            )
+            actions.append(action)
+
+        # For container nodes whose children also have actions (e.g. tabs or dropdowns)
+        for child in node.children:
+            self._collect_actions(child, file_path, fp_helper, actions)

sphinx_mkdocs_migrate/rules/models.py

@@ -0,0 +1,176 @@
+"""Data models for declarative migration rules, requirements, and preservation constraints."""
+
+from enum import Enum
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+from ..parsing.markdown_ir import NodeKind, BaseIRNode
+from ..analyzer.models import Classification
+
+
+class RuleKind(str, Enum):
+    """How the mapping rule is determined and evaluated."""
+
+    DETERMINISTIC = "DETERMINISTIC"  # 1-to-1 unambiguous structural transformation
+    EXTENSION_DEPENDENT = (
+        "EXTENSION_DEPENDENT"  # Relies on target Sphinx extensions (e.g. sphinx-design)
+    )
+    RULE_DEPENDENT = (
+        "RULE_DEPENDENT"  # Requires semantic inspection of symbol/environment
+    )
+    MANUAL_FALLBACK = "MANUAL_FALLBACK"  # Fallback when no automated mapping exists
+
+
+class MigrationTarget(BaseModel):
+    """Target Sphinx/MyST construct specification."""
+
+    framework: str = "MyST"  # e.g., "MyST", "sphinx-design", "sphinx.ext.autodoc", "sphinxcontrib-mermaid"
+    directive_name: str  # e.g., "note", "tab-set", "tab-item", "dropdown", "literalinclude", "mermaid"
+    syntax_template: Optional[str] = (
+        None  # e.g. "```{directive_name} {title}\n{body}\n```"
+    )
+    required_extensions: List[str] = Field(
+        default_factory=list
+    )  # e.g. ["sphinx_design", "myst_parser"]
+    required_py_packages: List[str] = Field(
+        default_factory=list
+    )  # e.g. ["sphinx-design", "myst-parser"]
+
+
+class MigrationRule(BaseModel):
+    """Declarative specification defining how a source IR construct maps to a Sphinx target."""
+
+    rule_id: str
+    source_kind: NodeKind
+    rule_kind: RuleKind
+    target: MigrationTarget
+    classification: Classification = Classification.TRANSFORM
+
+    # Declarative constraints and semantics
+    preserves: List[str] = Field(default_factory=list)  # Contract promises
+    changes: List[str] = Field(default_factory=list)  # Expected changes
+    conditions: Dict[str, Any] = Field(default_factory=dict)  # Evaluation conditions
+    manual_if: List[str] = Field(
+        default_factory=list
+    )  # Trigger conditions for manual classification
+    description: str
+
+    def matches(self, node: BaseIRNode) -> bool:
+        """Determines if this rule applies to the given IR node."""
+        return node.kind == self.source_kind
+
+    def evaluate(self, node: BaseIRNode) -> "RuleEvaluation":
+        """Generically evaluates the node against this rule's declarations without engine hardcoding."""
+        is_manual = False
+        manual_reasons: List[str] = []
+        applied_changes = list(self.changes)
+        resolved_target = self.target.model_copy(deep=True)
+
+        # Dynamic target resolution based on node metadata
+        if self.source_kind == NodeKind.ADMONITION:
+            adm_type = (node.metadata.get("admonition_type") or "note").lower()
+            supported_map = self.conditions.get("type_map", {})
+            if supported_map:
+                if adm_type in supported_map:
+                    resolved_target.directive_name = supported_map[adm_type]
+                    applied_changes.append(
+                        f"map_admonition_{adm_type}_to_{resolved_target.directive_name}"
+                    )
+                else:
+                    is_manual = True
+                    manual_reasons.append(
+                        f"Unsupported custom admonition type '{adm_type}'"
+                    )
+
+        elif self.source_kind == NodeKind.API_DIRECTIVE:
+            symbol = node.metadata.get("symbol", "<unknown>")
+            if self.classification == Classification.MANUAL:
+                is_manual = True
+                manual_reasons.append(
+                    f"Manual review required for API symbol '{symbol}'."
+                )
+            elif not symbol or symbol == "<unknown>":
+                is_manual = True
+                manual_reasons.append(
+                    f"Review API symbol '{symbol}' docstring convention and select autodoc directive."
+                )
+            else:
+                applied_changes.append(f"map_api_directive_{symbol}")
+
+        elif self.source_kind == NodeKind.LINK_REF:
+            href = node.metadata.get("href", "")
+            is_ext = node.metadata.get("is_external", False)
+            if is_ext:
+                applied_changes = ["preserve_external_url"]
+            elif href.endswith(".md") or ".md#" in href:
+                applied_changes = ["resolve_internal_doc_ref"]
+            else:
+                applied_changes = ["preserve_standard_link"]
+
+        # Derive truthful observed preservation for this specific node
+        observed_preservation: List[str] = []
+        for attr in self.preserves:
+            if attr in node.metadata:
+                observed_preservation.append(attr)
+            elif attr == "raw_text" and bool(node.raw_text):
+                observed_preservation.append(attr)
+            elif attr in ("tab_titles", "child_contents", "nesting") and bool(
+                node.children
+            ):
+                observed_preservation.append(attr)
+            elif attr == "body" and (bool(node.children) or bool(node.raw_text)):
+                observed_preservation.append(attr)
+            elif attr in ("diagram_source", "line_mapping", "link_text", "target_url"):
+                observed_preservation.append(attr)
+
+        # Determine final classification
+        final_class = Classification.MANUAL if is_manual else self.classification
+        action_item = "; ".join(manual_reasons) if manual_reasons else None
+
+        return RuleEvaluation(
+            rule_id=self.rule_id,
+            matched=True,
+            classification=final_class,
+            target=resolved_target if not is_manual else None,
+            applied_changes=applied_changes,
+            preserved_attributes=observed_preservation,
+            required_extensions=list(resolved_target.required_extensions),
+            required_packages=list(resolved_target.required_py_packages),
+            action_item=action_item,
+            rationale=self.description,
+        )
+
+
+class RuleEvaluation(BaseModel):
+    """Result of evaluating a MigrationRule against a specific DocumentIR node."""
+
+    rule_id: str
+    matched: bool
+    classification: Classification
+    target: Optional[MigrationTarget] = None
+    applied_changes: List[str] = Field(default_factory=list)
+    preserved_attributes: List[str] = Field(default_factory=list)
+    required_extensions: List[str] = Field(default_factory=list)
+    required_packages: List[str] = Field(default_factory=list)
+    action_item: Optional[str] = None
+    rationale: str
+
+
+class MigrationAction(BaseModel):
+    """Normalized, source-span-derived migration action for inventory aggregation and transformation."""
+
+    action_id: str
+    rule_id: str
+    source_file: str
+    start_line: int
+    end_line: int
+    classification: Classification
+    source_kind: NodeKind
+    source_span_fingerprint: str = (
+        ""  # SHA256 of the exact original raw text in [start_line, end_line]
+    )
+    target_directive: Optional[str] = None
+    required_extensions: List[str] = Field(default_factory=list)
+    required_packages: List[str] = Field(default_factory=list)
+    preserves: List[str] = Field(default_factory=list)
+    manual_instruction: Optional[str] = None
+    description: str