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

sphinx_mkdocs_migrate/planner/accountability.py

@@ -0,0 +1,111 @@
+"""Data models and inventory structures for Construct Accountability (Milestone 3.5 / 0.2.0).
+
+Orthogonal Dimensions:
+1. Source Occurrence: kind, file, span (start_line, end_line), occurrence text
+2. Disposition: PRESERVE | TRANSFORM | MANUAL | UNSUPPORTED
+3. Target Strategy: strategy name, emitted target directive/representation, target reference
+4. Verification State: UNVERIFIED | ACCOUNTED | VERIFIED
+5. Manual Action: required (bool), instruction, rationale
+"""
+
+from enum import Enum
+from typing import List, Dict, Optional, Tuple
+from pydantic import BaseModel, Field
+
+
+class ConstructDisposition(str, Enum):
+    """What should happen to the source construct during migration."""
+
+    PRESERVE = "PRESERVE"  # Preserve source representation/content through migration
+    TRANSFORM = "TRANSFORM"  # Automatically transform to target Sphinx/MyST construct
+    MANUAL = "MANUAL"  # Requires human decision or manual migration action
+    UNSUPPORTED = "UNSUPPORTED"  # Known limitation; not automatically supported
+
+
+class ConstructVerification(str, Enum):
+    """Has the construct outcome been verified?"""
+
+    UNVERIFIED = "UNVERIFIED"  # Discovered in source but not yet accounted for in plan
+    ACCOUNTED = "ACCOUNTED"  # Cataloged with explicit disposition and strategy in plan
+    VERIFIED = "VERIFIED"  # Proven valid via post-migration parse, build, or human confirmation
+
+
+class SourceOccurrence(BaseModel):
+    """Exact source provenance and location of an observed construct."""
+
+    kind: (
+        str  # e.g., "admonition", "code_fence", "tab_set", "heading", "link", "toctree"
+    )
+    file: str  # Relative file path (e.g. "docs/index.md", "mkdocs.yml")
+    span: Tuple[int, int]  # (start_line, end_line)
+    occurrence: Optional[str] = None  # Representative snippet or identifier
+
+
+class TargetStrategy(BaseModel):
+    """Planned target representation and emission strategy in Sphinx/MyST."""
+
+    strategy: str  # e.g., "myst_admonition", "direct_fence", "sphinx_design_tab", "root_toctree"
+    emitted: Optional[str] = None  # Exact generated directive / snippet
+    target_reference: Optional[str] = (
+        None  # Directive name, anchor ID, or conf variable
+    )
+
+
+class ManualActionSpec(BaseModel):
+    """Specification of human action requirements."""
+
+    required: bool = False
+    instruction: Optional[str] = None
+    rationale: Optional[str] = None
+
+
+class ConstructRecord(BaseModel):
+    """An individual accountable construct tracked across the full migration lifecycle."""
+
+    record_id: str
+    source: SourceOccurrence
+    disposition: ConstructDisposition
+    target: TargetStrategy
+    verification: ConstructVerification = ConstructVerification.ACCOUNTED
+    manual_action: ManualActionSpec = Field(default_factory=ManualActionSpec)
+
+
+class AccountabilityInventory(BaseModel):
+    """Repository-wide construct accountability matrix."""
+
+    records: List[ConstructRecord] = Field(default_factory=list)
+
+    @property
+    def total_count(self) -> int:
+        return len(self.records)
+
+    @property
+    def accounted_count(self) -> int:
+        return sum(
+            1
+            for r in self.records
+            if r.verification
+            in (ConstructVerification.ACCOUNTED, ConstructVerification.VERIFIED)
+        )
+
+    @property
+    def verified_count(self) -> int:
+        return sum(
+            1 for r in self.records if r.verification == ConstructVerification.VERIFIED
+        )
+
+    @property
+    def manual_count(self) -> int:
+        return sum(1 for r in self.records if r.manual_action.required)
+
+    def by_disposition(self) -> Dict[str, int]:
+        counts: Dict[str, int] = {}
+        for r in self.records:
+            counts[r.disposition.value] = counts.get(r.disposition.value, 0) + 1
+        return counts
+
+    def by_kind(self) -> Dict[str, int]:
+        counts: Dict[str, int] = {}
+        for r in self.records:
+            counts[r.source.kind] = counts.get(r.source.kind, 0) + 1
+        return counts

sphinx_mkdocs_migrate/planner/ci.py

@@ -0,0 +1,142 @@
+"""CI/CD and test runner migration planner."""
+
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Optional
+from pydantic import BaseModel
+from ..analyzer.ci import (
+    DEFAULT_CHECKOUT_TAG,
+    DEFAULT_CHECKOUT_SHA,
+    DEFAULT_SETUP_UV_TAG,
+    DEFAULT_SETUP_UV_SHA,
+)
+from ..analyzer.models import CIAnalysis, DependencyAnalysis
+
+
+class CIWorkflowPlan(BaseModel):
+    """Planned CI workflow updates for building Sphinx documentation."""
+
+    tox_docs_env: Optional[str] = None
+    github_docs_job: Optional[str] = None
+    checkout_pinned_ref: Optional[str] = None
+    setup_uv_pinned_ref: Optional[str] = None
+
+
+def determine_tox_dependency_line(
+    dep_analysis: Optional[DependencyAnalysis],
+    project_root: Optional[Path] = None,
+) -> str:
+    """Determine the dependency configuration line for tox [testenv:docs]."""
+    if (
+        dep_analysis
+        and dep_analysis.source_group_type
+        and dep_analysis.source_group_name
+    ):
+        if dep_analysis.source_group_type == "dependency-groups":
+            return f"dependency_groups = {dep_analysis.source_group_name}"
+        elif dep_analysis.source_group_type == "optional-dependencies":
+            return f"extras = {dep_analysis.source_group_name}"
+        elif dep_analysis.source_group_type == "requirements":
+            return f"deps = -r {dep_analysis.source_group_name}"
+
+    if project_root is not None:
+        pyproject_path = project_root / "pyproject.toml"
+        if pyproject_path.exists():
+            try:
+                py_text = pyproject_path.read_text(encoding="utf-8")
+                if "[dependency-groups]" in py_text:
+                    if re.search(r"^\s*docs\s*=", py_text, re.MULTILINE):
+                        return "dependency_groups = docs"
+                    elif re.search(r"^\s*documentation\s*=", py_text, re.MULTILINE):
+                        return "dependency_groups = documentation"
+                    elif re.search(r"^\s*dev\s*=", py_text, re.MULTILINE):
+                        return "dependency_groups = dev"
+                elif "[project.optional-dependencies]" in py_text:
+                    if re.search(r"^\s*docs\s*=", py_text, re.MULTILINE):
+                        return "extras = docs"
+                    elif re.search(r"^\s*doc\s*=", py_text, re.MULTILINE):
+                        return "extras = doc"
+                    elif re.search(r"^\s*dev\s*=", py_text, re.MULTILINE):
+                        return "extras = dev"
+            except Exception:
+                pass
+        if (project_root / "docs" / "requirements.txt").exists():
+            return "deps = -r docs/requirements.txt"
+        elif (project_root / "requirements.txt").exists():
+            return "deps = -r requirements.txt"
+
+    return "dependency_groups = dev"
+
+
+def build_tox_docs_env(
+    dep_config_line: str,
+    build_command: str = "sphinx-build -b html docs site/_build/html",
+) -> str:
+    """Build the [testenv:docs] section string for tox.ini."""
+    return f"""
+[testenv:docs]
+description = build documentation
+{dep_config_line}
+commands =
+    {build_command}
+"""
+
+
+def build_github_docs_job(
+    checkout_ref: str,
+    uv_ref: str,
+    tox_env: str = "docs",
+) -> str:
+    """Build the GitHub Actions documentation job block."""
+    return f"""
+  docs:
+    name: "Python Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@{checkout_ref}
+
+      - uses: astral-sh/setup-uv@{uv_ref}
+
+      - name: Build docs with tox
+        run: uvx tox -e {tox_env}
+"""
+
+
+def plan_ci_workflow(
+    ci_analysis: Optional[CIAnalysis],
+    dep_analysis: Optional[DependencyAnalysis],
+    project_root: Optional[Path] = None,
+) -> CIWorkflowPlan:
+    """Plan concrete CI changes based on observed repository evidence."""
+    dep_line = determine_tox_dependency_line(dep_analysis, project_root)
+    tox_env = build_tox_docs_env(dep_line)
+
+    default_chk = (
+        f"{DEFAULT_CHECKOUT_SHA} # {DEFAULT_CHECKOUT_TAG}"
+        if DEFAULT_CHECKOUT_SHA
+        else DEFAULT_CHECKOUT_TAG
+    )
+    default_uv = (
+        f"{DEFAULT_SETUP_UV_SHA} # {DEFAULT_SETUP_UV_TAG}"
+        if DEFAULT_SETUP_UV_SHA
+        else DEFAULT_SETUP_UV_TAG
+    )
+    ch_ref = (
+        ci_analysis.checkout_pinned_ref
+        if (ci_analysis and ci_analysis.checkout_pinned_ref)
+        else default_chk
+    )
+    uv_ref = (
+        ci_analysis.setup_uv_pinned_ref
+        if (ci_analysis and ci_analysis.setup_uv_pinned_ref)
+        else default_uv
+    )
+    gh_job = build_github_docs_job(checkout_ref=ch_ref, uv_ref=uv_ref)
+
+    return CIWorkflowPlan(
+        tox_docs_env=tox_env,
+        github_docs_job=gh_job,
+        checkout_pinned_ref=ch_ref,
+        setup_uv_pinned_ref=uv_ref,
+    )

sphinx_mkdocs_migrate/planner/conf_builder.py

@@ -0,0 +1,183 @@
+"""Sphinx conf.py configuration builder and code synthesizer."""
+
+from __future__ import annotations
+import pprint
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import MigrationPlan, ConfigMigrationProposal
+
+
+def build_conf_py(
+    plan: Optional[MigrationPlan] = None,
+    cfg: Optional[ConfigMigrationProposal] = None,
+    project_root: Optional[Path] = None,
+    plan_hash: Optional[str] = None,
+    has_generated_docs: bool = False,
+) -> str:
+    """Generates a clean Sphinx conf.py based strictly on MigrationPlan requirements."""
+    if plan is not None:
+        cfg = cfg or plan.proposed_sphinx_config
+        project_root = project_root or Path(plan.project_root)
+        plan_hash = plan_hash or plan.canonical_hash()[:12]
+        has_generated_docs = bool(plan.generated_documents)
+
+    project_name = cfg.project_name if cfg else "Documentation"
+    theme = (
+        cfg.theme.target_theme
+        if cfg and cfg.theme and cfg.theme.target_theme
+        else "sphinx_rtd_theme"
+    )
+    extensions = list(cfg.extensions_to_add) if cfg else ["myst_parser"]
+    myst_exts = list(cfg.myst_enable_extensions) if cfg else ["colon_fence"]
+    custom_opts = cfg.custom_options if cfg else {}
+
+    copyright_val = custom_opts.get("copyright", "Documentation Authors")
+    author_val = custom_opts.get("author", "Documentation Authors")
+
+    hash_str = plan_hash if plan_hash else "synthetic"
+    lines = [
+        "# Configuration file for Sphinx documentation generator.",
+        f"# Generated automatically by sphinx-mkdocs-migrate from plan: {hash_str}",
+        "import os",
+        "import sys",
+    ]
+
+    has_autodoc = any("autodoc" in ext for ext in extensions) or has_generated_docs
+    if has_autodoc:
+        if project_root is not None:
+            src_candidate = project_root / "src"
+            if src_candidate.exists() and src_candidate.is_dir():
+                lines.append("sys.path.insert(0, os.path.abspath('../src'))")
+        else:
+            lines.append("sys.path.insert(0, os.path.abspath('../src'))")
+        lines.append("sys.path.insert(0, os.path.abspath('..'))")
+
+    lines.extend(
+        [
+            "",
+            f"project = {repr(project_name)}",
+            f"copyright = {repr(copyright_val)}",
+            f"author = {repr(author_val)}",
+            "",
+            "extensions = [",
+        ]
+    )
+    for ext in sorted(extensions):
+        lines.append(f"    {repr(ext)},")
+    lines.append("]")
+    lines.extend(
+        [
+            "",
+            "source_suffix = {",
+            "    '.md': 'markdown',",
+            "}",
+            "",
+            f"html_theme = {repr(theme)}",
+        ]
+    )
+
+    # Standard scalar and list Sphinx configuration keys
+    standard_settings = [
+        "html_logo",
+        "html_favicon",
+        "language",
+        "html_css_files",
+        "html_js_files",
+        "html_title",
+        "html_baseurl",
+        "version",
+        "release",
+        "autosummary_generate",
+        "add_module_names",
+        "autoclass_content",
+        "autodoc_mock_imports",
+    ]
+    for key in standard_settings:
+        if key in custom_opts and custom_opts[key] is not None:
+            lines.append(f"{key} = {repr(custom_opts[key])}")
+
+    if "html_theme_options" in custom_opts:
+        formatted_opts = pprint.pformat(custom_opts["html_theme_options"], indent=4)
+        lines.extend(
+            [
+                "",
+                f"html_theme_options = {formatted_opts}",
+            ]
+        )
+    elif theme == "sphinx_immaterial":
+        lines.extend(
+            [
+                "",
+                "html_theme_options = {",
+                "    'font': False,",
+                "    'globaltoc_collapse': False,",
+                "}",
+            ]
+        )
+
+    if "object_description_options" in custom_opts:
+        formatted_obj_opts = pprint.pformat(
+            custom_opts["object_description_options"], indent=4
+        )
+        lines.extend(
+            [
+                "",
+                f"object_description_options = {formatted_obj_opts}",
+            ]
+        )
+    elif theme == "sphinx_immaterial":
+        lines.extend(
+            [
+                "",
+                "object_description_options = [",
+                "    ('py:.*', dict(include_fields_in_toc=False)),",
+                "    ('py:parameter', dict(include_in_toc=False)),",
+                "]",
+            ]
+        )
+
+    lines.extend(
+        [
+            "",
+            "myst_enable_extensions = [",
+        ]
+    )
+    for m_ext in sorted(myst_exts):
+        lines.append(f"    {repr(m_ext)},")
+    lines.extend(["]", "", "myst_heading_anchors = 3", ""])
+
+    if cfg and "sphinx.ext.autodoc" in cfg.extensions_to_add:
+        lines.extend(
+            [
+                "",
+                "import re",
+                "_re_md_link = re.compile(r'(?<![!])\\[(?P<text>[^\\]\\n]+?)\\]\\((?P<url>[^\\)\\s]+)\\)')",
+                "_re_cross_ref = re.compile(r'(?<![!])\\[(?P<text>[^\\]\\n]+?)\\]\\[(?P<target>[a-zA-Z_0-9\\.]+)\\]')",
+                "_re_empty_cross_ref = re.compile(r'(?<![!])\\[(?P<target>[a-zA-Z_0-9\\.]+)\\]\\[\\]')",
+                "_re_md_code = re.compile(r'(?<![:`])`(?P<code>[^`\\n]+?)`(?!_|\\`)')",
+                "",
+                "def process_docstrings(app, what, name, obj, options, lines):",
+                "    if what == 'module' and getattr(options, 'members', None):",
+                "        lines.clear()",
+                "        return",
+                "    for i in range(len(lines)):",
+                "        if '[' in lines[i] and '][' in lines[i]:",
+                "            lines[i] = _re_empty_cross_ref.sub(r':py:obj:`\\g<target>`', lines[i])",
+                "            lines[i] = _re_cross_ref.sub(r':py:obj:`\\g<text> <\\g<target>>`', lines[i])",
+                "        if '[' in lines[i] and '](' in lines[i]:",
+                "            def repl(m):",
+                "                clean_text = m.group('text').replace('`', '').strip()",
+                "                return f'`{clean_text} <{m.group(\"url\")}>`_'",
+                "            lines[i] = _re_md_link.sub(repl, lines[i])",
+                "        if '`' in lines[i]:",
+                "            lines[i] = _re_md_code.sub(r'``\\g<code>``', lines[i])",
+                "",
+                "def setup(app):",
+                "    app.connect('autodoc-process-docstring', process_docstrings)",
+                "",
+            ]
+        )
+
+    return "\n".join(lines)