mystquarto 0.1.0__tar.gz

mystquarto-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

mystquarto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Ghenis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mystquarto-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: mystquarto
+Version: 0.1.0
+Summary: Bidirectional MyST ↔ Quarto converter
+Project-URL: Homepage, https://github.com/MaxGhenis/mystquarto
+Project-URL: Repository, https://github.com/MaxGhenis/mystquarto
+Author: Max Ghenis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: converter,markdown,myst,quarto
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# mystquarto
+
+Bidirectional MyST ↔ Quarto converter.
+
+## Installation
+
+```bash
+pip install mystquarto
+# or
+uvx mystquarto
+```
+
+## Usage
+
+```bash
+# Convert MyST → Quarto
+myst2quarto docs/
+mystquarto to-quarto docs/
+
+# Convert Quarto → MyST
+quarto2myst docs/
+mystquarto to-myst docs/
+```
+
+### Options
+
+- `--output DIR` / `-o DIR`: Output directory (default: converts in-place)
+- `--in-place`: Modify files in-place
+- `--config-only`: Only convert config files (myst.yml ↔ _quarto.yml)
+- `--no-config`: Skip config file conversion
+- `--dry-run`: Show what would be changed without writing
+- `--strict`: Treat warnings as errors

mystquarto-0.1.0/README.md

@@ -0,0 +1,32 @@
+# mystquarto
+
+Bidirectional MyST ↔ Quarto converter.
+
+## Installation
+
+```bash
+pip install mystquarto
+# or
+uvx mystquarto
+```
+
+## Usage
+
+```bash
+# Convert MyST → Quarto
+myst2quarto docs/
+mystquarto to-quarto docs/
+
+# Convert Quarto → MyST
+quarto2myst docs/
+mystquarto to-myst docs/
+```
+
+### Options
+
+- `--output DIR` / `-o DIR`: Output directory (default: converts in-place)
+- `--in-place`: Modify files in-place
+- `--config-only`: Only convert config files (myst.yml ↔ _quarto.yml)
+- `--no-config`: Skip config file conversion
+- `--dry-run`: Show what would be changed without writing
+- `--strict`: Treat warnings as errors

mystquarto-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mystquarto"
+version = "0.1.0"
+description = "Bidirectional MyST ↔ Quarto converter"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Max Ghenis" }]
+keywords = ["myst", "quarto", "markdown", "converter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+    "click>=8.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+myst2quarto = "mystquarto.cli:myst2quarto"
+quarto2myst = "mystquarto.cli:quarto2myst"
+mystquarto = "mystquarto.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MaxGhenis/mystquarto"
+Repository = "https://github.com/MaxGhenis/mystquarto"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88

mystquarto-0.1.0/src/mystquarto/__init__.py

@@ -0,0 +1,3 @@
+"""Bidirectional MyST ↔ Quarto converter."""
+
+__version__ = "0.1.0"

mystquarto-0.1.0/src/mystquarto/cli.py

@@ -0,0 +1,175 @@
+"""Click CLI for mystquarto: bidirectional MyST <-> Quarto converter."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from mystquarto.convert import Direction, convert_directory
+from mystquarto.warnings import WarningCollector
+
+
+def _run_conversion(
+    path: str,
+    output: str | None,
+    in_place: bool,
+    config_only: bool,
+    no_config: bool,
+    dry_run: bool,
+    strict: bool,
+    direction: Direction,
+) -> None:
+    """Shared implementation for both conversion directions.
+
+    Args:
+        path: Input file or directory path.
+        output: Output directory path (or None).
+        in_place: Whether to modify files in-place.
+        config_only: Only convert config files.
+        no_config: Skip config file conversion.
+        dry_run: Show what would change without writing.
+        strict: Treat warnings as errors.
+        direction: Conversion direction.
+    """
+    collector = WarningCollector(strict=strict)
+
+    results = convert_directory(
+        input_dir=path,
+        output_dir=output,
+        direction=direction,
+        in_place=in_place,
+        config_only=config_only,
+        no_config=no_config,
+        dry_run=dry_run,
+    )
+
+    # Collect warnings and errors from results
+    for result in results:
+        for warning in result.warnings:
+            collector.warn(warning)
+        for error in result.errors:
+            collector.error(error)
+
+    # Report
+    converted_count = sum(
+        1 for r in results if not r.skipped and not r.errors
+    )
+    label = "Would convert" if dry_run else "Converted"
+
+    if dry_run:
+        for result in results:
+            if not result.skipped and result.output_path:
+                click.echo(f"  {result.input_path} -> {result.output_path}")
+
+    click.echo(f"{label} {converted_count} file(s).")
+
+    if collector.warnings or collector.errors:
+        click.echo(collector.report())
+
+    if collector.has_errors():
+        sys.exit(1)
+
+
+@click.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), help="Output directory")
+@click.option("--in-place", is_flag=True, help="Modify files in-place")
+@click.option("--config-only", is_flag=True, help="Only convert config files")
+@click.option("--no-config", is_flag=True, help="Skip config file conversion")
+@click.option(
+    "--dry-run", is_flag=True, help="Show what would change without writing"
+)
+@click.option("--strict", is_flag=True, help="Treat warnings as errors")
+def myst2quarto(path, output, in_place, config_only, no_config, dry_run, strict):
+    """Convert MyST markdown files to Quarto format."""
+    _run_conversion(
+        path=path,
+        output=output,
+        in_place=in_place,
+        config_only=config_only,
+        no_config=no_config,
+        dry_run=dry_run,
+        strict=strict,
+        direction=Direction.MYST_TO_QUARTO,
+    )
+
+
+@click.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), help="Output directory")
+@click.option("--in-place", is_flag=True, help="Modify files in-place")
+@click.option("--config-only", is_flag=True, help="Only convert config files")
+@click.option("--no-config", is_flag=True, help="Skip config file conversion")
+@click.option(
+    "--dry-run", is_flag=True, help="Show what would change without writing"
+)
+@click.option("--strict", is_flag=True, help="Treat warnings as errors")
+def quarto2myst(path, output, in_place, config_only, no_config, dry_run, strict):
+    """Convert Quarto markdown files to MyST format."""
+    _run_conversion(
+        path=path,
+        output=output,
+        in_place=in_place,
+        config_only=config_only,
+        no_config=no_config,
+        dry_run=dry_run,
+        strict=strict,
+        direction=Direction.QUARTO_TO_MYST,
+    )
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def main(ctx):
+    """Bidirectional MyST <-> Quarto converter."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+@main.command("to-quarto")
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), help="Output directory")
+@click.option("--in-place", is_flag=True, help="Modify files in-place")
+@click.option("--config-only", is_flag=True, help="Only convert config files")
+@click.option("--no-config", is_flag=True, help="Skip config file conversion")
+@click.option(
+    "--dry-run", is_flag=True, help="Show what would change without writing"
+)
+@click.option("--strict", is_flag=True, help="Treat warnings as errors")
+def to_quarto(path, output, in_place, config_only, no_config, dry_run, strict):
+    """Convert MyST markdown files to Quarto format."""
+    _run_conversion(
+        path=path,
+        output=output,
+        in_place=in_place,
+        config_only=config_only,
+        no_config=no_config,
+        dry_run=dry_run,
+        strict=strict,
+        direction=Direction.MYST_TO_QUARTO,
+    )
+
+
+@main.command("to-myst")
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), help="Output directory")
+@click.option("--in-place", is_flag=True, help="Modify files in-place")
+@click.option("--config-only", is_flag=True, help="Only convert config files")
+@click.option("--no-config", is_flag=True, help="Skip config file conversion")
+@click.option(
+    "--dry-run", is_flag=True, help="Show what would change without writing"
+)
+@click.option("--strict", is_flag=True, help="Treat warnings as errors")
+def to_myst(path, output, in_place, config_only, no_config, dry_run, strict):
+    """Convert Quarto markdown files to MyST format."""
+    _run_conversion(
+        path=path,
+        output=output,
+        in_place=in_place,
+        config_only=config_only,
+        no_config=no_config,
+        dry_run=dry_run,
+        strict=strict,
+        direction=Direction.QUARTO_TO_MYST,
+    )

mystquarto-0.1.0/src/mystquarto/config.py

@@ -0,0 +1,271 @@
+"""Config conversion: myst.yml <-> _quarto.yml."""
+
+from __future__ import annotations
+
+import os
+
+import yaml
+
+
+def _is_book_project(myst_config: dict) -> bool:
+    """Detect if a MyST config represents a book-type project.
+
+    Book type is indicated by either:
+    - site.template == "book-theme"
+    - presence of project.toc
+    """
+    site = myst_config.get("site", {})
+    if site.get("template") == "book-theme":
+        return True
+    project = myst_config.get("project", {})
+    if "toc" in project:
+        return True
+    return False
+
+
+def _toc_to_chapters(toc: list[dict]) -> list[str]:
+    """Convert MyST toc entries to Quarto chapter file list.
+
+    Each entry is a dict with a 'file' key (with or without extension).
+    Returns list of filenames with .qmd extension.
+    """
+    chapters = []
+    for entry in toc:
+        if isinstance(entry, dict) and "file" in entry:
+            name = entry["file"]
+        elif isinstance(entry, str):
+            name = entry
+        else:
+            continue
+        # Strip existing .md extension before adding .qmd
+        if name.endswith(".md"):
+            name = name[:-3]
+        chapters.append(f"{name}.qmd")
+    return chapters
+
+
+def _chapters_to_toc(chapters: list[str]) -> list[dict]:
+    """Convert Quarto chapter file list to MyST toc entries.
+
+    Each chapter is a filename (possibly with .qmd extension).
+    Returns list of dicts with 'file' key (no extension).
+    """
+    toc = []
+    for chapter in chapters:
+        filename = chapter
+        # Strip .qmd or .md extension
+        for ext in (".qmd", ".md"):
+            if filename.endswith(ext):
+                filename = filename[: -len(ext)]
+                break
+        toc.append({"file": filename})
+    return toc
+
+
+def _convert_authors_myst_to_quarto(authors: list[dict]) -> list[dict]:
+    """Convert MyST author entries to Quarto format.
+
+    Both use similar structures with name and affiliations.
+    """
+    result = []
+    for author in authors:
+        entry = {}
+        if "name" in author:
+            entry["name"] = author["name"]
+        if "affiliations" in author:
+            entry["affiliations"] = author["affiliations"]
+        # Pass through any other fields
+        for key, value in author.items():
+            if key not in ("name", "affiliations"):
+                entry[key] = value
+        result.append(entry)
+    return result
+
+
+def _convert_exports_to_format(exports: list[dict]) -> dict:
+    """Convert MyST exports list to Quarto format block.
+
+    Each export has a 'format' key (pdf, docx, etc.) and other options.
+    """
+    format_block = {}
+    for export in exports:
+        fmt = export.get("format")
+        if not fmt:
+            continue
+        # Copy all options except 'format' itself
+        options = {k: v for k, v in export.items() if k != "format"}
+        format_block[fmt] = options if options else {}
+    return format_block
+
+
+def _convert_format_to_exports(format_block: dict) -> list[dict]:
+    """Convert Quarto format block to MyST exports list."""
+    exports = []
+    for fmt, options in format_block.items():
+        export = {"format": fmt}
+        if isinstance(options, dict):
+            export.update(options)
+        exports.append(export)
+    return exports
+
+
+def myst_to_quarto_config(myst_config: dict) -> dict:
+    """Convert a parsed myst.yml dict to a _quarto.yml dict.
+
+    Handles both book-type and article/manuscript projects.
+    """
+    if not myst_config:
+        return {}
+
+    project = myst_config.get("project", {})
+    if not project:
+        return {}
+
+    result = {}
+    is_book = _is_book_project(myst_config)
+
+    if is_book:
+        # Book-type project
+        result["project"] = {"type": "book"}
+        book = {}
+
+        if "title" in project:
+            book["title"] = project["title"]
+        if "authors" in project:
+            book["author"] = _convert_authors_myst_to_quarto(project["authors"])
+        if "toc" in project:
+            book["chapters"] = _toc_to_chapters(project["toc"])
+
+        result["book"] = book
+    else:
+        # Article/manuscript project
+        if "title" in project:
+            result["title"] = project["title"]
+        if "authors" in project:
+            result["author"] = _convert_authors_myst_to_quarto(project["authors"])
+
+    # Fields that apply to both types
+    if "bibliography" in project:
+        result["bibliography"] = project["bibliography"]
+
+    if "exports" in project:
+        result["format"] = _convert_exports_to_format(project["exports"])
+
+    if "github" in project:
+        result["repo-url"] = project["github"]
+
+    if "license" in project:
+        result["license"] = project["license"]
+
+    if "keywords" in project:
+        result["keywords"] = project["keywords"]
+
+    if "date" in project:
+        result["date"] = project["date"]
+
+    if "subject" in project:
+        result["description"] = project["subject"]
+
+    return result
+
+
+def quarto_to_myst_config(quarto_config: dict) -> dict:
+    """Convert a parsed _quarto.yml dict to a myst.yml dict.
+
+    Handles both book-type and article/manuscript projects.
+    """
+    if not quarto_config:
+        return {}
+
+    result = {}
+    project = {}
+    is_book = (
+        quarto_config.get("project", {}).get("type") == "book"
+        or "book" in quarto_config
+    )
+
+    if is_book:
+        book = quarto_config.get("book", {})
+        if "title" in book:
+            project["title"] = book["title"]
+        if "author" in book:
+            project["authors"] = book["author"]
+        if "chapters" in book:
+            project["toc"] = _chapters_to_toc(book["chapters"])
+        result["site"] = {"template": "book-theme"}
+    else:
+        if "title" in quarto_config:
+            project["title"] = quarto_config["title"]
+        if "author" in quarto_config:
+            project["authors"] = quarto_config["author"]
+
+    # Fields that apply to both types
+    if "bibliography" in quarto_config:
+        project["bibliography"] = quarto_config["bibliography"]
+
+    if "format" in quarto_config:
+        project["exports"] = _convert_format_to_exports(quarto_config["format"])
+
+    if "repo-url" in quarto_config:
+        project["github"] = quarto_config["repo-url"]
+
+    if "license" in quarto_config:
+        project["license"] = quarto_config["license"]
+
+    if "keywords" in quarto_config:
+        project["keywords"] = quarto_config["keywords"]
+
+    if "date" in quarto_config:
+        project["date"] = quarto_config["date"]
+
+    if "description" in quarto_config:
+        project["subject"] = quarto_config["description"]
+
+    if project:
+        result["project"] = project
+
+    return result
+
+
+def convert_myst_config(myst_yml_path: str, output_dir: str) -> str:
+    """Read myst.yml, convert to _quarto.yml, write to output_dir.
+
+    Args:
+        myst_yml_path: Path to the input myst.yml file.
+        output_dir: Directory to write _quarto.yml to.
+
+    Returns:
+        Path to the output _quarto.yml file.
+    """
+    with open(myst_yml_path) as f:
+        myst_config = yaml.safe_load(f) or {}
+
+    quarto_config = myst_to_quarto_config(myst_config)
+
+    output_path = os.path.join(output_dir, "_quarto.yml")
+    with open(output_path, "w") as f:
+        yaml.dump(quarto_config, f, default_flow_style=False, sort_keys=False)
+
+    return output_path
+
+
+def convert_quarto_config(quarto_yml_path: str, output_dir: str) -> str:
+    """Read _quarto.yml, convert to myst.yml, write to output_dir.
+
+    Args:
+        quarto_yml_path: Path to the input _quarto.yml file.
+        output_dir: Directory to write myst.yml to.
+
+    Returns:
+        Path to the output myst.yml file.
+    """
+    with open(quarto_yml_path) as f:
+        quarto_config = yaml.safe_load(f) or {}
+
+    myst_config = quarto_to_myst_config(quarto_config)
+
+    output_path = os.path.join(output_dir, "myst.yml")
+    with open(output_path, "w") as f:
+        yaml.dump(myst_config, f, default_flow_style=False, sort_keys=False)
+
+    return output_path