chaptr 0.1.1__py3-none-any.whl

chaptr/cli.py

@@ -0,0 +1,264 @@
+import argparse
+import html
+import re
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+import yaml
+from markdown_it import MarkdownIt
+
+from chaptr.render import render_document
+
+
+class BuildError(ValueError):
+    pass
+
+
+def substitute(source: str, variables: dict[str, str], filename: Path) -> str:
+    lines = source.splitlines(keepends=True)
+    protected = set()
+    for token in MarkdownIt().parse(source):
+        if token.type in {"fence", "code_block"} and token.map:
+            protected.update(range(*token.map))
+    pattern = re.compile(r"\$\$|\$([A-Za-z_][A-Za-z0-9_]*)")
+
+    def replace(match: re.Match[str], line_number: int) -> str:
+        name = match.group(1)
+        if name is None:
+            return "$"
+        if name not in variables:
+            raise BuildError(f"{filename}:{line_number}: undefined variable ${name}")
+        return variables[name]
+
+    result = []
+    for line_number, line in enumerate(lines, 1):
+        if line_number - 1 in protected:
+            result.append(line)
+            continue
+        parts = re.split(r"(`+[^`]*`+)", line)
+        result.append("".join(
+            part if index % 2 else pattern.sub(
+                lambda match: replace(match, line_number), part
+            )
+            for index, part in enumerate(parts)
+        ))
+    return "".join(result)
+
+
+def load_config(path: Path) -> dict:
+    config = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(config, dict):
+        raise BuildError("Configuration must be a YAML mapping.")
+    chapters = config.get("files")
+    if not isinstance(chapters, list) or not chapters or not all(
+        isinstance(chapter, str) for chapter in chapters
+    ):
+        raise BuildError("files must be a nonempty list of Markdown paths.")
+    variables = config.get("variables", {})
+    if not isinstance(variables, dict) or not all(
+        isinstance(name, str)
+        and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name)
+        and isinstance(value, (str, int, float, bool))
+        for name, value in variables.items()
+    ):
+        raise BuildError("variables must map valid names to scalar values.")
+    for name in ("title", "theme", "output", "stylesheet", "author", "subtitle", "front_cover", "back_cover", "author_section"):
+        if name in config and not isinstance(config[name], str):
+            raise BuildError(f"{name} must be a string.")
+    for name in ("title_page", "table_of_contents"):
+        if name in config and not isinstance(config[name], bool):
+            raise BuildError(f"{name} must be true or false.")
+    if "toc_depth" in config and (type(config["toc_depth"]) is not int or not 1 <= config["toc_depth"] <= 6):
+        raise BuildError("toc_depth must be an integer from 1 to 6.")
+    return config
+
+
+def theme_css(root: Path, name: str, stylesheet: str | None) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", name):
+        raise BuildError("theme must be a simple name, such as modern or vintage.")
+    bundled = files("chaptr").joinpath("themes")
+    local = root / "themes" / f"{name}.css"
+    theme = local if local.is_file() else bundled.joinpath(f"{name}.css")
+    if not theme.is_file():
+        raise BuildError(f"Unknown theme: {name}")
+    css = bundled.joinpath("base.css").read_text(encoding="utf-8")
+    css += "\n" + theme.read_text(encoding="utf-8")
+    if stylesheet:
+        css += "\n" + (root / stylesheet).read_text(encoding="utf-8")
+    return css
+
+
+def build(config_path: Path, format_name: str = "html", theme: str | None = None) -> Path:
+    config_path = config_path.resolve()
+    root = config_path.parent
+    config = load_config(config_path)
+    variables = {name: str(value) for name, value in config.get("variables", {}).items()}
+    chapters = []
+    source_files = []
+    pdf_covers = {
+        field: root / config[field]
+        for field in ("front_cover", "back_cover")
+        if config.get(field) and Path(config[field]).suffix.lower() == ".pdf"
+    }
+    for field, role in (("front_cover", "front-cover"), ("author_section", "author-section")):
+        if config.get(field) and field not in pdf_covers:
+            source_files.append((config[field], role))
+    source_files.extend((filename, "chapter") for filename in config["files"])
+    if config.get("back_cover") and "back_cover" not in pdf_covers:
+        source_files.append((config["back_cover"], "back-cover"))
+    for filename, role in source_files:
+        path = root / filename
+        source = substitute(path.read_text(encoding="utf-8"), variables, path)
+        chapters.append((source, path, role))
+    output = root / config.get("output", "build")
+    suffix = {"markdown": "md", "html": "html", "pdf": "pdf"}[format_name]
+    destination = output / f"document.{suffix}"
+    if format_name == "pdf" and any(path.resolve() == destination.resolve() for path in pdf_covers.values()):
+        raise BuildError("A PDF cover cannot also be the output document. Choose a different cover path or output directory.")
+    if format_name == "markdown":
+        content = "\n\n".join(source.rstrip() for source, path, role in chapters) + "\n"
+    else:
+        css = theme_css(root, theme or config.get("theme", "modern"), config.get("stylesheet"))
+        if format_name == "pdf" and "front_cover" in pdf_covers:
+            css += "\n@page:first { counter-reset: page 2; }\n"
+        title = html.escape(config.get("title", "Document"))
+        content = (
+            '<!doctype html>\n<html lang="en"><head><meta charset="utf-8">'
+            '<meta name="viewport" content="width=device-width, initial-scale=1">'
+            f"<title>{title}</title><style>{css}</style></head>"
+            f'<body><main>{render_document(chapters, config)}</main></body></html>\n'
+        )
+    if format_name == "pdf":
+        try:
+            from weasyprint import HTML
+        except (ImportError, OSError) as error:
+            raise BuildError(
+                "PDF requires the pdf extra and WeasyPrint's native libraries. "
+                "Run 'chaptr help' for PDF requirements. " + str(error)
+            ) from error
+        document = HTML(string=content, base_url=str(root)).write_pdf()
+        if pdf_covers:
+            try:
+                from chaptr.pdf import CoverError, merge_covers
+            except ImportError as error:
+                raise BuildError("PDF covers require pypdf. Install chaptr's pdf extra.") from error
+            try:
+                document = merge_covers(document, pdf_covers)
+            except CoverError as error:
+                raise BuildError(str(error)) from error
+        output.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(document)
+    else:
+        output.mkdir(parents=True, exist_ok=True)
+        destination.write_text(content, encoding="utf-8")
+    return destination
+
+
+def init_project(directory: Path) -> Path:
+    root = directory.resolve()
+    starter_files = {
+        resource.name: resource.read_text(encoding="utf-8")
+        for resource in files("chaptr_docs").iterdir()
+        if resource.is_file() and Path(resource.name).suffix in {".md", ".yaml", ".css"}
+    }
+    starter_files[".gitignore"] = "build/\n"
+    if root.exists() and not root.is_dir():
+        raise BuildError(f"Project directory is not a directory: {root}")
+    conflicts = [
+        name for name in starter_files
+        if (root / name).exists() or (root / name).is_symlink()
+    ]
+    if conflicts:
+        raise BuildError("Refusing to overwrite existing project files: " + ", ".join(conflicts))
+    root.mkdir(parents=True, exist_ok=True)
+    for name, content in starter_files.items():
+        with (root / name).open("x", encoding="utf-8") as destination:
+            destination.write(content)
+    return root / "document.yaml"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="chaptr",
+        description="Build independent Markdown document projects with variables and CSS themes.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  chaptr init my-document\n"
+            "  chaptr build --format pdf\n"
+            "  chaptr build --config path/to/document.yaml\n"
+            "  chaptr build --help\n\n"
+            "Run 'chaptr help' for the full usage manual."
+        ),
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    initializer = commands.add_parser(
+        "init",
+        help="Create an editable project containing chaptr's documentation.",
+        description="Copy chaptr's documentation, configuration, stylesheet and a build-output ignore rule.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  chaptr init\n"
+            "  chaptr init my-document\n\n"
+            "Existing starter files are never overwritten. Read or edit the\n"
+            "documentation sections, then run 'chaptr build' from the project directory.\n"
+            "Initialization does not require PDF dependencies."
+        ),
+    )
+    initializer.add_argument(
+        "directory", nargs="?", type=Path, default=Path("."), metavar="DIRECTORY",
+        help="Project directory to create or use (default: current directory).",
+    )
+    command = commands.add_parser(
+        "build",
+        help="Build ordered chapters from a project configuration.",
+        description="Combine configured Markdown chapters and write one document.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  chaptr build\n"
+            "  chaptr build --format pdf\n"
+            "  chaptr build --config path/to/document.yaml --format markdown\n"
+            "  chaptr build --theme vintage\n\n"
+            "Project paths are relative to the configuration file. Output defaults\n"
+            "to build/document.<extension> within that project; existing output\n"
+            "of the same format is replaced. PDF requires WeasyPrint and its\n"
+            "native libraries. Run 'chaptr help' for configuration and theme details."
+        ),
+    )
+    command.add_argument(
+        "--config", type=Path, default=Path("document.yaml"), metavar="PATH",
+        help="YAML project configuration (default: document.yaml in the current directory).",
+    )
+    command.add_argument(
+        "--format", choices=["markdown", "html", "pdf"], default="html",
+        help="Output format (default: html); PDF requires optional renderer dependencies.",
+    )
+    command.add_argument(
+        "--theme", metavar="NAME",
+        help="Override the configured CSS theme for HTML/PDF; ignored for Markdown.",
+    )
+    commands.add_parser("help", help="Print the full usage manual.")
+    args = parser.parse_args()
+    if args.command == "help":
+        print(files("chaptr").joinpath("manual.txt").read_text(encoding="utf-8"), end="")
+        return 0
+    try:
+        if args.command == "init":
+            config_path = init_project(args.directory)
+            print(f"Initialized project at {config_path.parent}")
+            print("Start with README.md, then edit document.yaml and the Markdown sections.")
+            print(f'Build with: chaptr build --config "{config_path.as_posix()}"')
+            return 0
+        destination = build(args.config, args.format, args.theme)
+    except (BuildError, OSError, yaml.YAMLError) as error:
+        print(f"chaptr: {error}", file=sys.stderr)
+        return 1
+    print(destination)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chaptr/manual.txt

@@ -0,0 +1,210 @@
+CHAPTR - Markdown document builder
+
+NAME
+    chaptr - combine a document project's Markdown chapters into one output file
+
+SYNOPSIS
+    chaptr --help
+    chaptr help
+    chaptr init [DIRECTORY]
+    chaptr init --help
+    chaptr build [--config PATH] [--format {markdown,html,pdf}] [--theme NAME]
+    chaptr build --help
+
+DESCRIPTION
+    Install the CLI once and use it with any number of document projects.
+    Each project contains a YAML configuration and Markdown source files.
+
+COMMANDS
+    init
+        Create an editable copy of chaptr's documentation in DIRECTORY or the current
+        directory if omitted. Missing directories are created automatically.
+        The default project contains the documentation sections, README.md,
+        document.yaml, styles.css and a .gitignore excluding build output.
+        Read README.md or build the documentation, then adapt it to your content.
+        No output is rendered during init. Template selection is not supported
+        yet; see the copied roadmap section for future plans.
+
+        Existing starter files are never overwritten. Conflicts are checked
+        before writing; unrelated files are kept. If a starter file already
+        exists, choose a different directory. No --force option is provided.
+        Initialization is noninteractive and needs no PDF dependencies.
+
+    build
+        Read the configuration, substitute variables and combine chapters in
+        the listed order. HTML and PDF use CSS themes; Markdown is unstyled.
+        A successful build prints the absolute path of the generated file.
+
+    help
+        Print this manual. No document project or PDF dependencies are needed.
+
+OPTIONS
+    -h, --help
+        Show a short command overview. Use chaptr init --help or chaptr build --help
+        for command-specific usage.
+
+    DIRECTORY (init only)
+        Optional project directory to create or use. Default: current directory.
+        Quote paths containing spaces.
+
+    --config PATH
+        YAML configuration to load. Default: document.yaml in the current
+        directory. Paths inside it are relative to the configuration file,
+        regardless of where you run chaptr.
+
+    --format {markdown,html,pdf}
+        Output format. Default: html.
+        markdown produces merged source, html produces a styled browser
+        document and pdf produces a printable document via WeasyPrint.
+
+    --theme NAME
+        Override the configured theme for this build. Applies to HTML and PDF
+        only; ignored for Markdown. Bundled names: modern and vintage.
+
+CONFIGURATION
+    Minimal document.yaml:
+
+        files:
+          - notes.md
+
+    Extended document.yaml:
+
+        title: Product Guide
+        theme: modern
+        stylesheet: styles.css
+        output: build
+        files:
+          - chapters/introduction.md
+          - chapters/requirements.md
+        variables:
+          product_name: Field Notes
+          version: "1.0"
+
+    files       Required, nonempty list of source paths in chapter order.
+    title       HTML document title; default: Document.
+    theme       Named CSS theme; default: modern.
+    stylesheet  Optional extra CSS path, applied after the theme.
+    output      Output directory; default: build.
+    variables   Optional mapping of names to text, numbers or booleans.
+    title_page  Generate a title page; default: false.
+    subtitle    Plain-text title-page subtitle; default: empty.
+    author      Plain-text title-page author; default: empty.
+    front_cover Markdown or single-page PDF front cover; default: none.
+    author_section Markdown file for author details; default: none.
+    table_of_contents Generate linked contents; default: false.
+    toc_depth   Contents heading depth, 1 to 6; default: 2.
+    back_cover  Markdown or single-page PDF back cover; default: none.
+
+DOCUMENT FEATURES
+    Put Table: Caption text in a standalone paragraph directly above or below
+    a Markdown table. Captioned tables are numbered across the document in source
+    order. Tables without captions remain unnumbered. Use one caption per table.
+
+    Use [^label] references and [^label]: Note text definitions for footnotes.
+    Labels are document-wide. Numbered notes appear at the end with return links.
+
+    Optional page order: front cover, title page, author section, contents,
+    chapters, notes and back cover. Cover and author files use ordinary Markdown.
+    Do not list them again in files. Contents include only chapter headings.
+    HTML contents are linked; PDF contents include page numbers.
+
+    Title pages, contents and numbered captions are generated for HTML/PDF only.
+    Merged Markdown includes authored covers and author sections and preserves
+    caption and footnote source syntax.
+
+PDF COVERS
+    Configure front_cover: covers/front.pdf or back_cover: covers/back.pdf.
+    PDF builds attach those pages around the generated content using pypdf.
+    Artwork and fonts are preserved without scaling or generated page margins.
+    Either cover is optional and Markdown and PDF covers can be mixed.
+
+    Each PDF cover must be unencrypted, contain exactly one page and match the
+    adjacent generated page's size within one PDF point. Invalid covers fail
+    before existing output is replaced. Cover files cannot be the output file.
+
+    An inserted front cover counts as page 1; generated contents page numbers
+    match the final PDF's physical pages. Links and bookmarks are preserved.
+    HTML and Markdown builds omit PDF covers. Bleed and trim setup is not provided.
+
+VARIABLES
+    Write $product_name in Markdown to insert its configured value.
+    Write $$ for a literal dollar sign, for example $$20 becomes $20.
+    Names contain letters, digits or underscores and cannot start with a digit.
+    Undefined names stop the build with a source filename and line number.
+    Values are inserted as Markdown.
+    Code blocks and ordinary inline code are left unchanged.
+
+THEMES
+    CSS is applied in this order:
+        1. Bundled base styling.
+        2. Project themes/NAME.css if present, otherwise bundled NAME.css.
+        3. The optional stylesheet specified in the configuration.
+
+    To create a theme, add themes/company.css and set theme: company.
+    A local themes/modern.css replaces only that project's modern theme.
+    Use @media print for PDF-specific rules and @page for size and margins.
+    The base print layout uses A4, 20mm margins and a new page per chapter.
+    Relative CSS asset URLs currently resolve from the project root.
+
+OUTPUT
+    The selected output directory receives one file per build:
+        document.md     --format markdown
+        document.html   --format html
+        document.pdf    --format pdf
+
+    Rebuilding a format replaces its existing file. Other formats are untouched.
+    Open HTML directly in a browser.
+
+PDF REQUIREMENTS
+    The pdf extra includes WeasyPrint and pypdf for PDF cover assembly.
+    Developer installation from the application repository:
+        python -m pip install -e ".[pdf]"
+
+    WeasyPrint also requires native libraries, including Pango. Installing the
+    Python package alone may not be sufficient. Platform installation guide:
+        https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation
+
+    If native libraries are missing, PDF builds fail; HTML and Markdown still
+    work. Self-contained executable releases are not available yet.
+
+EXAMPLES
+    Create a document project and build its documentation:
+        chaptr init my-document
+        cd my-document
+        chaptr build
+
+    Initialize an existing directory or a path containing spaces:
+        chaptr init
+        chaptr init "My Document"
+
+    Build HTML from the current document project:
+        chaptr build
+
+    Build its PDF:
+        chaptr build --format pdf
+
+    Build a project from another directory, including a path with spaces:
+        chaptr build --config "C:/Documents/Product Guide/document.yaml" --format pdf
+        chaptr build --config /home/user/product-guide/document.yaml --format pdf
+
+    Export merged Markdown or select another theme:
+        chaptr build --format markdown
+        chaptr build --theme vintage
+
+EXIT STATUS
+    0   Success, including help output.
+    1   Initialization or build failure, such as existing starter files, invalid
+        configuration, missing files or variables, unknown themes or missing
+        PDF renderer dependencies.
+    2   Invalid command-line usage, such as an unknown option or format.
+
+LIMITATIONS
+    Build trusted local projects only: PDF rendering may read files or fetch URLs.
+    Raw source HTML and mathematical notation are not supported.
+    Substitution does not yet preserve multiline inline code.
+    Cross-file Markdown links are not converted into internal document links.
+    Footnotes are collected at the document's end, not at each PDF page's bottom.
+    HTML/PDF resolve relative image and link paths against their source chapter.
+    HTML uses local file references, which must remain available. Merged Markdown
+    retains source link paths, which may require adjustment after merging.
+    Browser and WeasyPrint CSS support differ; test print styling in actual PDF.

chaptr/pdf.py

@@ -0,0 +1,52 @@
+from io import BytesIO
+from pathlib import Path
+
+from pypdf import PdfReader, PdfWriter
+from pypdf.errors import PdfReadError
+
+
+class CoverError(ValueError):
+    pass
+
+
+def page_size(page) -> tuple[float, float]:
+    scale = float(page.get("/UserUnit", 1))
+    width = float(page.mediabox.width) * scale
+    height = float(page.mediabox.height) * scale
+    return (height, width) if page.rotation % 180 else (width, height)
+
+
+def merge_covers(content: bytes, covers: dict[str, Path]) -> bytes:
+    body = PdfReader(BytesIO(content))
+    readers = {}
+    for role, path in covers.items():
+        try:
+            reader = PdfReader(BytesIO(path.read_bytes()))
+            if reader.is_encrypted:
+                raise CoverError(f"{role}: encrypted PDF covers are not supported: {path}")
+            if len(reader.pages) != 1:
+                raise CoverError(f"{role}: PDF cover must contain exactly one page: {path}")
+            expected = page_size(body.pages[0 if role == "front_cover" else -1])
+            actual = page_size(reader.pages[0])
+            if any(abs(actual_dimension - expected_dimension) > 1 for actual_dimension, expected_dimension in zip(actual, expected)):
+                raise CoverError(
+                    f"{role}: cover size {actual[0]:.1f} x {actual[1]:.1f} pt "
+                    f"does not match document size {expected[0]:.1f} x {expected[1]:.1f} pt: {path}"
+                )
+            readers[role] = reader
+        except (OSError, PdfReadError, ValueError) as error:
+            if isinstance(error, CoverError):
+                raise
+            raise CoverError(f"{role}: cannot read PDF cover {path}: {error}") from error
+    writer = PdfWriter()
+    if "front_cover" in readers:
+        writer.append(readers["front_cover"])
+    writer.append(body)
+    if "back_cover" in readers:
+        writer.append(readers["back_cover"])
+    if body.metadata:
+        writer.add_metadata({key: value for key, value in body.metadata.items() if isinstance(value, str)})
+    destination = BytesIO()
+    writer.write(destination)
+    writer.close()
+    return destination.getvalue()