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

sphinx_mkdocs_migrate/__init__.py

@@ -0,0 +1,8 @@
+"""Sphinx MkDocs Migrate.
+
+Deterministic, evidence-driven analyzer and migration engine from MkDocs to Sphinx + MyST.
+"""
+
+# PEP 440 developmental release version
+__version__ = "0.0.1.dev0"
+__all__ = ["__version__"]

sphinx_mkdocs_migrate/analyzer/__init__.py

@@ -0,0 +1,17 @@
+"""Analyzer subsystem module."""
+
+from .project import ProjectAnalyzer
+from .models import (
+    ProjectAnalysisReport,
+    Classification,
+    ConstructFinding,
+    SubsystemSummary,
+)
+
+__all__ = [
+    "ProjectAnalyzer",
+    "ProjectAnalysisReport",
+    "Classification",
+    "ConstructFinding",
+    "SubsystemSummary",
+]

sphinx_mkdocs_migrate/analyzer/ci.py

@@ -0,0 +1,223 @@
+"""Subsystem analyzer for CI/CD, local test runners, and deployment workflows."""
+
+import re
+from pathlib import Path
+from typing import Optional, List, Dict, Tuple
+from .models import CIAnalysis
+
+DEFAULT_CHECKOUT_TAG = "v7.0.1"
+DEFAULT_CHECKOUT_SHA = "3d3c42e5aac5ba805825da76410c181273ba90b1"
+DEFAULT_SETUP_UV_TAG = "v10.2.0"
+DEFAULT_SETUP_UV_SHA = "c18668ad3cf93ea998bef934396af7bb5c839dc7"
+
+
+def resolve_github_action_ref(
+    action_repo: str, fallback_tag: str, fallback_sha: str
+) -> Tuple[str, str]:
+    """Resolves the latest release tag and commit SHA for a GitHub Action repository via git ls-remote."""
+    import subprocess
+
+    try:
+        url = f"https://github.com/{action_repo}.git"
+        out = subprocess.check_output(
+            ["git", "ls-remote", "--tags", url],
+            text=True,
+            timeout=5,
+            stdin=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        tag_shas: Dict[str, str] = {}
+        for line in out.splitlines():
+            parts = line.split()
+            if len(parts) >= 2:
+                sha, ref = parts[0], parts[1]
+                m = re.match(r"^refs/tags/(v?[0-9]+(?:\.[0-9]+)*)(\^\{\})?$", ref)
+                if m:
+                    tag = m.group(1)
+                    if ref.endswith("^{}"):
+                        tag_shas[tag] = sha
+                    elif tag not in tag_shas:
+                        tag_shas[tag] = sha
+        if tag_shas:
+
+            def semver_key(t: str):
+                return [int(x) for x in re.findall(r"[0-9]+", t)]
+
+            sorted_tags = sorted(tag_shas.keys(), key=semver_key)
+            latest_tag = sorted_tags[-1]
+            return latest_tag, tag_shas[latest_tag]
+    except Exception:
+        pass
+    return fallback_tag, fallback_sha
+
+
+class CIAnalyzer:
+    """Discovers and inspects project CI/CD workflows, runners (tox/nox/make), and hosted doc configs."""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def analyze(self) -> CIAnalysis:
+        # 1. GitHub Actions (.github/workflows/*.yml)
+        github_workflows = self.project_root / ".github" / "workflows"
+        workflow_files: List[str] = []
+        docs_workflow_files: List[str] = []
+        has_deploy = False
+        has_tox_in_ci = False
+        has_uv_in_ci = False
+        has_gh_pages_action = False
+        checkout_ref: Optional[str] = None
+        setup_uv_ref: Optional[str] = None
+        checkout_pinned_ref: Optional[str] = None
+        setup_uv_pinned_ref: Optional[str] = None
+        github_actions_detected = github_workflows.is_dir()
+
+        if github_actions_detected:
+            chk_tag, chk_sha = resolve_github_action_ref(
+                "actions/checkout", DEFAULT_CHECKOUT_TAG, DEFAULT_CHECKOUT_SHA
+            )
+            uv_tag, uv_sha = resolve_github_action_ref(
+                "astral-sh/setup-uv", DEFAULT_SETUP_UV_TAG, DEFAULT_SETUP_UV_SHA
+            )
+            checkout_pinned_ref = f"{chk_sha} # {chk_tag}" if chk_sha else chk_tag
+            setup_uv_pinned_ref = f"{uv_sha} # {uv_tag}" if uv_sha else uv_tag
+
+        if github_actions_detected:
+            for yml_file in sorted(github_workflows.glob("*.y*ml")):
+                rel = yml_file.relative_to(self.project_root).as_posix()
+                workflow_files.append(rel)
+                try:
+                    content = yml_file.read_text(encoding="utf-8")
+                    if (
+                        "mkdocs gh-deploy" in content
+                        or "mkdocs build" in content
+                        or "mike deploy" in content
+                    ):
+                        has_deploy = True
+                        docs_workflow_files.append(rel)
+                    if "tox" in content or "uvx tox" in content:
+                        has_tox_in_ci = True
+                    if (
+                        "astral-sh/setup-uv" in content
+                        or "setup-uv" in content
+                        or "uv run" in content
+                    ):
+                        has_uv_in_ci = True
+                    if (
+                        "peaceiris/actions-gh-pages" in content
+                        or "actions/deploy-pages" in content
+                    ):
+                        has_gh_pages_action = True
+
+                    # Extract current action version refs
+                    m_chk = re.search(r"uses:\s*actions/checkout@([^\s\n]+)", content)
+                    if m_chk and not checkout_ref:
+                        checkout_ref = m_chk.group(1).split("#")[0].strip()
+                    m_uv = re.search(r"uses:\s*astral-sh/setup-uv@([^\s\n]+)", content)
+                    if m_uv and not setup_uv_ref:
+                        setup_uv_ref = m_uv.group(1).split("#")[0].strip()
+                except Exception:
+                    pass
+
+        # 2. Local test & doc runners: tox.ini
+        tox_ini = self.project_root / "tox.ini"
+        has_tox = tox_ini.is_file()
+        tox_file = (
+            tox_ini.relative_to(self.project_root).as_posix() if has_tox else None
+        )
+        tox_has_docs_env = False
+        tox_docs_commands: List[str] = []
+        tox_dependency_spec: Optional[str] = None
+
+        if has_tox:
+            try:
+                tox_text = tox_ini.read_text(encoding="utf-8")
+                if "[testenv:docs]" in tox_text:
+                    tox_has_docs_env = True
+                    # Extract section content
+                    m_sec = re.search(
+                        r"\[testenv:docs\](.*?)(?=\n\[|\Z)", tox_text, re.DOTALL
+                    )
+                    if m_sec:
+                        sec_text = m_sec.group(1)
+                        for line in sec_text.splitlines():
+                            line_s = line.strip()
+                            if (
+                                line_s.startswith("dependency_groups")
+                                or line_s.startswith("extras")
+                                or line_s.startswith("deps")
+                            ):
+                                tox_dependency_spec = line_s
+                            elif line_s.startswith("commands =") or (
+                                line.startswith(" ")
+                                and ("sphinx-build" in line_s or "mkdocs" in line_s)
+                            ):
+                                tox_docs_commands.append(line_s)
+                elif "mkdocs" in tox_text:
+                    tox_docs_commands.append("mkdocs")
+            except Exception:
+                pass
+
+        # 3. ReadTheDocs (.readthedocs.yaml or .readthedocs.yml)
+        rtd_config = self.project_root / ".readthedocs.yaml"
+        if not rtd_config.exists():
+            rtd_config = self.project_root / ".readthedocs.yml"
+        has_rtd = rtd_config.is_file()
+        rtd_file = (
+            rtd_config.relative_to(self.project_root).as_posix() if has_rtd else None
+        )
+
+        # 4. Nox runner (noxfile.py)
+        noxfile = self.project_root / "noxfile.py"
+        has_nox = noxfile.is_file()
+        nox_file = (
+            noxfile.relative_to(self.project_root).as_posix() if has_nox else None
+        )
+
+        # 5. Makefile
+        makefile = self.project_root / "Makefile"
+        has_makefile = makefile.is_file()
+
+        # 6. Pre-commit (.pre-commit-config.yaml)
+        pre_commit = self.project_root / ".pre-commit-config.yaml"
+        has_pre_commit = pre_commit.is_file()
+
+        # 7. GitLab CI (.gitlab-ci.yml)
+        gitlab_ci = self.project_root / ".gitlab-ci.yml"
+        gitlab_ci_detected = gitlab_ci.is_file()
+
+        # Primary CI system resolution
+        ci_system = None
+        if github_actions_detected:
+            ci_system = "github_actions"
+        elif gitlab_ci_detected:
+            ci_system = "gitlab_ci"
+        elif has_rtd:
+            ci_system = "readthedocs"
+
+        return CIAnalysis(
+            ci_system=ci_system,
+            workflow_files=workflow_files,
+            docs_workflow_files=docs_workflow_files,
+            has_mkdocs_deploy=has_deploy,
+            readthedocs_detected=has_rtd,
+            rtd_config_file=rtd_file,
+            github_actions_detected=github_actions_detected,
+            has_tox_in_ci=has_tox_in_ci,
+            has_uv_in_ci=has_uv_in_ci,
+            has_gh_pages_action=has_gh_pages_action,
+            checkout_action_ref=checkout_ref,
+            setup_uv_action_ref=setup_uv_ref,
+            checkout_pinned_ref=checkout_pinned_ref,
+            setup_uv_pinned_ref=setup_uv_pinned_ref,
+            has_tox=has_tox,
+            tox_file=tox_file,
+            tox_has_docs_env=tox_has_docs_env,
+            tox_docs_commands=tox_docs_commands,
+            tox_dependency_spec=tox_dependency_spec,
+            has_nox=has_nox,
+            nox_file=nox_file,
+            has_makefile=has_makefile,
+            has_pre_commit=has_pre_commit,
+            gitlab_ci_detected=gitlab_ci_detected,
+        )

sphinx_mkdocs_migrate/analyzer/dependencies.py

@@ -0,0 +1,134 @@
+from pathlib import Path
+from typing import Optional, Dict
+import importlib.metadata
+from ..parsing.requirements import (
+    parse_pyproject_toml,
+    parse_requirements_txt,
+    NormalizedManifest,
+)
+from .models import DependencyAnalysis, VersionEnvironment, PackageVersionInfo
+
+KNOWN_MKDOCS_PACKAGES = {
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings",
+    "mkdocstrings-python",
+    "mkdocs-material-extensions",
+    "pymdown-extensions",
+    "mkdocs-mermaid2-plugin",
+    "mike",
+    "mkdocs-autorefs",
+    "mkdocs-literate-nav",
+    "mkdocs-macros-plugin",
+    "mdx_truly_sane_lists",
+    "mkdocs-awesome-pages-plugin",
+    "mkdocs-gen-files",
+}
+
+
+class DependencyAnalyzer:
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def analyze(self) -> tuple[Optional[DependencyAnalysis], VersionEnvironment]:
+        pyproject = self.project_root / "pyproject.toml"
+        docs_req = self.project_root / "docs" / "requirements.txt"
+        req = self.project_root / "requirements.txt"
+
+        manifest: Optional[NormalizedManifest] = None
+        if pyproject.exists():
+            manifest = parse_pyproject_toml(pyproject)
+        elif docs_req.exists():
+            manifest = parse_requirements_txt(docs_req)
+        elif req.exists():
+            manifest = parse_requirements_txt(req)
+
+        if not manifest:
+            return None, VersionEnvironment()
+
+        to_remove = []
+        source_group_type: Optional[str] = None
+        source_group_name: Optional[str] = None
+        for dep in manifest.dependencies:
+            if dep.name in KNOWN_MKDOCS_PACKAGES:
+                to_remove.append(dep.name)
+                if not source_group_name and dep.source_location:
+                    if dep.source_location.startswith("dependency-groups."):
+                        source_group_type = "dependency-groups"
+                        source_group_name = dep.source_location.split(".", 1)[1]
+                    elif dep.source_location.startswith(
+                        "project.optional-dependencies."
+                    ):
+                        source_group_type = "optional-dependencies"
+                        source_group_name = dep.source_location.split(".", 2)[2]
+                    elif "requirements" in dep.source_location:
+                        source_group_type = "requirements"
+                        source_group_name = dep.source_location
+
+        suggested_to_add = ["sphinx", "myst-parser", "sphinx-design"]
+        if "mkdocs-material" in to_remove:
+            suggested_to_add.append("sphinx-immaterial")
+
+        dep_analysis = DependencyAnalysis(
+            manifest_type=manifest.manifest_type,
+            detected_packages_to_remove=sorted(list(set(to_remove))),
+            suggested_packages_to_add=suggested_to_add,
+            source_group_type=source_group_type,
+            source_group_name=source_group_name,
+        )
+
+        packages_info: Dict[str, PackageVersionInfo] = {}
+        plugin_vers: Dict[str, str] = {}
+        mkdocs_ver = None
+
+        import sys
+
+        current_py_ver = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+
+        for dep in manifest.dependencies:
+            if dep.name == "mkdocs" or dep.name in KNOWN_MKDOCS_PACKAGES:
+                # Check if installed in active environment
+                installed_ver = None
+                status = "DECLARED_ONLY"
+                res_source = "MANIFEST_DECLARATION"
+                satisfies_constraint = None
+
+                try:
+                    installed_ver = importlib.metadata.version(dep.name)
+                    status = "INSTALLED_RESOLVED"
+                    res_source = "CURRENT_PYTHON_ENVIRONMENT"
+                    # Basic constraint check if `>=` specified
+                    if ">=" in dep.raw_spec:
+                        req_ver = dep.raw_spec.split(">=")[-1].strip()
+                        satisfies_constraint = installed_ver >= req_ver
+                    else:
+                        satisfies_constraint = True
+                except Exception:
+                    pass
+
+                pkg_info = PackageVersionInfo(
+                    package_name=dep.name,
+                    declared_spec=dep.raw_spec,
+                    resolved_version=installed_ver,
+                    resolution_status=status,
+                    resolution_source=res_source,
+                    satisfies_declared_constraint=satisfies_constraint,
+                )
+                packages_info[dep.name] = pkg_info
+
+                if dep.name == "mkdocs":
+                    mkdocs_ver = dep.raw_spec
+                else:
+                    plugin_vers[dep.name] = dep.raw_spec
+
+        version_env = VersionEnvironment(
+            python_version=manifest.python_requirement,
+            python_constraint=manifest.python_requirement,
+            python_resolved_version=current_py_ver,
+            python_resolution_status="INSTALLED_RESOLVED",
+            packages=packages_info,
+            detected_mkdocs_version=mkdocs_ver,
+            detected_plugin_versions=plugin_vers,
+        )
+
+        return dep_analysis, version_env

sphinx_mkdocs_migrate/analyzer/markdown.py

@@ -0,0 +1,148 @@
+"""Markdown AST analyzer inspecting DocumentIR nodes to extract migration findings."""
+
+from pathlib import Path
+from typing import List, Tuple, Optional
+from ..parsing.markdown import MarkdownParser
+from ..parsing.markdown_ir import NodeKind, BaseIRNode
+from .models import ConstructFinding, Classification
+
+
+class MarkdownAnalyzer:
+    """Analyzes Markdown files by parsing them into DocumentIR and recording migration findings."""
+
+    def __init__(self, project_root: Optional[Path] = None):
+        self.project_root = project_root
+        self.parser = MarkdownParser()
+
+    def analyze_file(self, file_path: Path) -> List[ConstructFinding]:
+        if not file_path.exists():
+            return []
+
+        doc_ir = self.parser.parse_file(file_path)
+        findings: List[ConstructFinding] = []
+
+        def visit_node(node: BaseIRNode):
+            snippet = (
+                node.raw_text.splitlines()[0]
+                if node.raw_text.splitlines()
+                else f"<{node.kind.value}>"
+            )
+
+            if node.kind == NodeKind.ADMONITION:
+                findings.append(
+                    ConstructFinding(
+                        category="Markdown",
+                        construct_type="admonition",
+                        file_path=doc_ir.file_path,
+                        line_number=node.start_line,
+                        end_line_number=node.end_line,
+                        raw_snippet=snippet,
+                        classification=Classification.TRANSFORM,
+                        metadata={
+                            "admonition_type": node.metadata.get("admonition_type"),
+                            "title": node.metadata.get("title"),
+                        },
+                    )
+                )
+            elif node.kind == NodeKind.DETAILS_DROPDOWN:
+                findings.append(
+                    ConstructFinding(
+                        category="Markdown",
+                        construct_type="details_dropdown",
+                        file_path=doc_ir.file_path,
+                        line_number=node.start_line,
+                        end_line_number=node.end_line,
+                        raw_snippet=snippet,
+                        classification=Classification.TRANSFORM,
+                        metadata={"title": node.metadata.get("title")},
+                    )
+                )
+            elif node.kind == NodeKind.TAB_SET:
+                findings.append(
+                    ConstructFinding(
+                        category="Markdown",
+                        construct_type="tab_set",
+                        file_path=doc_ir.file_path,
+                        line_number=node.start_line,
+                        end_line_number=node.end_line,
+                        raw_snippet=snippet,
+                        classification=Classification.TRANSFORM,
+                        metadata={"tab_count": len(node.children)},
+                    )
+                )
+            elif node.kind == NodeKind.API_DIRECTIVE:
+                findings.append(
+                    ConstructFinding(
+                        category="API Documentation",
+                        construct_type="mkdocstrings",
+                        file_path=doc_ir.file_path,
+                        line_number=node.start_line,
+                        end_line_number=node.end_line,
+                        raw_snippet=snippet,
+                        classification=Classification.MANUAL,
+                        metadata={"symbol": node.metadata.get("symbol")},
+                    )
+                )
+            elif node.kind == NodeKind.SNIPPET_INCLUDE:
+                findings.append(
+                    ConstructFinding(
+                        category="Markdown",
+                        construct_type="snippet_include",
+                        file_path=doc_ir.file_path,
+                        line_number=node.start_line,
+                        end_line_number=node.end_line,
+                        raw_snippet=snippet,
+                        classification=Classification.TRANSFORM,
+                        metadata={"filepath": node.metadata.get("filepath")},
+                    )
+                )
+            elif node.kind == NodeKind.MERMAID_DIAGRAM:
+                findings.append(
+                    ConstructFinding(
+                        category="Markdown",
+                        construct_type="mermaid_diagram",
+                        file_path=doc_ir.file_path,
+                        line_number=node.start_line,
+                        end_line_number=node.end_line,
+                        raw_snippet=snippet,
+                        classification=Classification.TRANSFORM,
+                        metadata={},
+                    )
+                )
+            elif node.kind == NodeKind.LINK_REF:
+                href = node.metadata.get("href", "")
+                if href.endswith(".md") or ".md#" in href:
+                    findings.append(
+                        ConstructFinding(
+                            category="Markdown",
+                            construct_type="document_link",
+                            file_path=doc_ir.file_path,
+                            line_number=node.start_line,
+                            end_line_number=node.end_line,
+                            raw_snippet=href,
+                            classification=Classification.PRESERVE,
+                            metadata={"href": href, "text": node.metadata.get("text")},
+                        )
+                    )
+
+            # Recurse children
+            for child in node.children:
+                visit_node(child)
+
+        for root_node in doc_ir.nodes:
+            visit_node(root_node)
+
+        return findings
+
+    def analyze_directory(self, docs_dir: Path) -> Tuple[int, List[ConstructFinding]]:
+        if not docs_dir.exists():
+            return 0, []
+
+        all_findings: List[ConstructFinding] = []
+        md_files = list(docs_dir.rglob("*.md"))
+
+        for md_file in md_files:
+            file_findings = self.analyze_file(md_file)
+            all_findings.extend(file_findings)
+
+        return len(md_files), all_findings