docs2epub 0.1.0__tar.gz → 0.1.2__tar.gz

{docs2epub-0.1.0 → docs2epub-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docs2epub
-Version: 0.1.0
+Version: 0.1.2
 Summary: Turn documentation sites into an EPUB (Kindle-friendly).
 Author: Breno Brito
 License: MIT
@@ -31,6 +31,21 @@ uv run docs2epub --help
 
 ## Usage
 
+### uvx (no install)
+
+```bash
+uvx docs2epub \
+  https://www.techinterviewhandbook.org/software-engineering-interview-guide/ \
+  tech-interview-handbook.epub
+
+# Optional (override inferred metadata)
+uvx docs2epub \
+  https://www.techinterviewhandbook.org/software-engineering-interview-guide/ \
+  tech-interview-handbook.epub \
+  --title "Tech Interview Handbook" \
+  --author "Yangshun Tay"
+```
+
 ### Docusaurus “Next” crawl
 
 ```bash

{docs2epub-0.1.0 → docs2epub-0.1.2}/README.md

@@ -15,6 +15,21 @@ uv run docs2epub --help
 
 ## Usage
 
+### uvx (no install)
+
+```bash
+uvx docs2epub \
+  https://www.techinterviewhandbook.org/software-engineering-interview-guide/ \
+  tech-interview-handbook.epub
+
+# Optional (override inferred metadata)
+uvx docs2epub \
+  https://www.techinterviewhandbook.org/software-engineering-interview-guide/ \
+  tech-interview-handbook.epub \
+  --title "Tech Interview Handbook" \
+  --author "Yangshun Tay"
+```
+
 ### Docusaurus “Next” crawl
 
 ```bash

{docs2epub-0.1.0 → docs2epub-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docs2epub"
-version = "0.1.0"
+version = "0.1.2"
 description = "Turn documentation sites into an EPUB (Kindle-friendly)."
 readme = "README.md"
 requires-python = ">=3.12"

{docs2epub-0.1.0 → docs2epub-0.1.2}/src/docs2epub/__init__.py

@@ -2,4 +2,4 @@ __all__ = [
   "__version__",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

docs2epub-0.1.2/src/docs2epub/cli.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .docusaurus_next import DocusaurusNextOptions, iter_docusaurus_next
+from .epub import EpubMetadata, build_epub
+from .pandoc_epub2 import PandocEpub2Options, build_epub2_with_pandoc
+
+
+def _infer_defaults(start_url: str) -> tuple[str, str, str]:
+  parsed = urlparse(start_url)
+  host = parsed.netloc or "docs"
+  title = host
+  author = host
+  language = "en"
+  return title, author, language
+
+
+def _build_parser() -> argparse.ArgumentParser:
+  p = argparse.ArgumentParser(
+    prog="docs2epub",
+    description="Turn documentation sites into an EPUB (Kindle-friendly).",
+  )
+
+  # Short positional form (for uvx):
+  #   docs2epub <START_URL> <OUT.epub>
+  p.add_argument(
+    "start_url_pos",
+    nargs="?",
+    help="Starting URL for scraping (initially: Docusaurus docs page).",
+  )
+  p.add_argument(
+    "out_pos",
+    nargs="?",
+    help="Output EPUB file path.",
+  )
+
+  # Flag form (more explicit):
+  p.add_argument(
+    "--start-url",
+    dest="start_url",
+    default=None,
+    help="Starting URL for scraping (overrides positional start_url).",
+  )
+  p.add_argument(
+    "--out",
+    dest="out",
+    default=None,
+    help="Output EPUB file path (overrides positional out).",
+  )
+
+  p.add_argument(
+    "--base-url",
+    default=None,
+    help="Base URL used to resolve relative links (defaults to start-url).",
+  )
+  p.add_argument("--max-pages", type=int, default=None)
+  p.add_argument("--sleep-s", type=float, default=0.5)
+
+  p.add_argument("--title", default=None)
+  p.add_argument("--author", default=None)
+  p.add_argument("--language", default=None)
+  p.add_argument("--identifier", default=None)
+  p.add_argument("--publisher", default=None)
+
+  p.add_argument(
+    "--format",
+    default="epub2",
+    choices=["epub2", "epub3"],
+    help="Output format. Default: epub2 (Kindle-friendly).",
+  )
+
+  p.add_argument(
+    "--keep-images",
+    action="store_true",
+    help="Keep and embed remote images (may be slower and can trigger fetch warnings).",
+  )
+
+  p.add_argument(
+    "-v",
+    "--verbose",
+    action="store_true",
+    help="Verbose output (shows full pandoc warnings).",
+  )
+
+  return p
+
+
+def main(argv: list[str] | None = None) -> int:
+  args = _build_parser().parse_args(argv)
+
+  start_url = args.start_url or args.start_url_pos
+  out_value = args.out or args.out_pos
+
+  if not start_url or not out_value:
+    raise SystemExit("Usage: docs2epub <START_URL> <OUT.epub> [options]")
+
+  inferred_title, inferred_author, inferred_language = _infer_defaults(start_url)
+
+  title = args.title or inferred_title
+  author = args.author or inferred_author
+  language = args.language or inferred_language
+
+  options = DocusaurusNextOptions(
+    start_url=start_url,
+    base_url=args.base_url,
+    max_pages=args.max_pages,
+    sleep_s=args.sleep_s,
+  )
+
+  chapters = iter_docusaurus_next(options)
+  if not chapters:
+    raise SystemExit("No pages scraped (did not find article content).")
+
+  out_path_value = Path(out_value)
+
+  if args.format == "epub2":
+    out_path = build_epub2_with_pandoc(
+      chapters=chapters,
+      out_file=out_path_value,
+      title=title,
+      author=author,
+      language=language,
+      publisher=args.publisher,
+      identifier=args.identifier,
+      verbose=args.verbose,
+      options=PandocEpub2Options(keep_images=args.keep_images),
+    )
+  else:
+    meta = EpubMetadata(
+      title=title,
+      author=author,
+      language=language,
+      identifier=args.identifier,
+      publisher=args.publisher,
+    )
+
+    out_path = build_epub(
+      chapters=chapters,
+      out_file=out_path_value,
+      meta=meta,
+    )
+
+  size_mb = out_path.stat().st_size / (1024 * 1024)
+  print(f"Scraped {len(chapters)} pages")
+  print(f"EPUB written to: {out_path.resolve()} ({size_mb:.2f} MB)")
+  return 0

{docs2epub-0.1.0 → docs2epub-0.1.2}/src/docs2epub/kindle_html.py

@@ -5,37 +5,45 @@ import re
 from bs4 import BeautifulSoup
 
 
-def clean_html_for_kindle_epub2(html_fragment: str) -> str:
+def clean_html_for_kindle_epub2(
+  html_fragment: str,
+  *,
+  keep_images: bool,
+) -> str:
   """Best-effort HTML cleanup for Kindle-friendly EPUB2.
 
   This is intentionally conservative: it strips known-problematic attributes
   and tags that commonly cause Send-to-Kindle conversion issues.
+
+  By default we drop remote images to avoid pandoc fetch failures.
   """
 
   soup = BeautifulSoup(html_fragment, "lxml")
 
+  if not keep_images:
+    for img in list(soup.find_all("img")):
+      src = str(img.get("src") or "")
+      if src.startswith("http://") or src.startswith("https://"):
+        img.decompose()
+
   # EPUB2: <u> tag isn't consistently supported; convert to a span.
   for u in list(soup.find_all("u")):
     span = soup.new_tag("span")
     span["style"] = "text-decoration: underline;"
-    span.string = u.get_text() if u.string is None else u.string
     if u.string is None:
-      # Keep children by moving them into the span.
       for child in list(u.contents):
         span.append(child)
+    else:
+      span.string = u.string
     u.replace_with(span)
 
   # Remove tabindex attributes (not allowed in EPUB2 XHTML).
   for el in soup.find_all(attrs={"tabindex": True}):
-    try:
-      del el["tabindex"]
-    except KeyError:
-      pass
+    el.attrs.pop("tabindex", None)
 
   # Remove start attribute from ordered lists (not allowed in EPUB2 XHTML).
   for ol in soup.find_all("ol"):
-    if ol.has_attr("start"):
-      del ol["start"]
+    ol.attrs.pop("start", None)
 
   # Strip duplicate ids in a simple way: if an id repeats, rename it.
   seen_ids: set[str] = set()
@@ -54,7 +62,6 @@ def clean_html_for_kindle_epub2(html_fragment: str) -> str:
     el["id"] = new_id
     seen_ids.add(new_id)
 
-  # Remove empty fragment links that point to missing ids (best-effort).
   # If href="#something" but no element has id="something", drop href.
   all_ids = {str(el.get("id")) for el in soup.find_all(attrs={"id": True})}
   for a in soup.find_all("a", href=True):
@@ -62,9 +69,9 @@ def clean_html_for_kindle_epub2(html_fragment: str) -> str:
     if href.startswith("#") and len(href) > 1:
       frag = href[1:]
       if frag not in all_ids:
-        del a["href"]
+        a.attrs.pop("href", None)
 
-  # Normalize weird whitespace artifacts.
+  # Normalize whitespace a bit (helps keep diffs smaller and reduces odd output).
   text = str(soup)
   text = re.sub(r"\s+", " ", text)
   return text.strip()

{docs2epub-0.1.0 → docs2epub-0.1.2}/src/docs2epub/pandoc_epub2.py

@@ -15,7 +15,8 @@ from .model import Chapter
 class PandocEpub2Options:
   toc: bool = True
   toc_depth: int = 2
-  chapter_level: int = 1
+  split_level: int = 1
+  keep_images: bool = False
 
 
 def _wrap_html(title: str, body_html: str) -> str:
@@ -34,6 +35,26 @@ def _wrap_html(title: str, body_html: str) -> str:
 """
 
 
+def _summarize_pandoc_warnings(stderr: str) -> str:
+  warnings = [line for line in stderr.splitlines() if line.startswith("[WARNING]")]
+  if not warnings:
+    return ""
+
+  resource = [w for w in warnings if "Could not fetch resource" in w]
+  duplicate = [w for w in warnings if "Duplicate identifier" in w]
+
+  parts: list[str] = []
+  parts.append(f"pandoc warnings: {len(warnings)} (use -v to see full output)")
+  if duplicate:
+    parts.append(f"- Duplicate identifier: {len(duplicate)} (usually safe; affects internal anchors)")
+  if resource:
+    parts.append(
+      f"- Missing resources: {len(resource)} (some images may be dropped; use --keep-images/-v to inspect)"
+    )
+
+  return "\n".join(parts)
+
+
 def build_epub2_with_pandoc(
   *,
   chapters: Iterable[Chapter],
@@ -43,6 +64,7 @@ def build_epub2_with_pandoc(
   language: str,
   publisher: str | None,
   identifier: str | None,
+  verbose: bool,
   options: PandocEpub2Options | None = None,
 ) -> Path:
   pandoc = shutil.which("pandoc")
@@ -61,7 +83,7 @@ def build_epub2_with_pandoc(
 
     html_files: list[Path] = []
     for ch in chapters:
-      cleaned = clean_html_for_kindle_epub2(ch.html)
+      cleaned = clean_html_for_kindle_epub2(ch.html, keep_images=opts.keep_images)
       html_doc = _wrap_html(ch.title, cleaned)
       fp = tmp_path / f"chapter_{ch.index:04d}.html"
       fp.write_text(html_doc, encoding="utf-8")
@@ -81,14 +103,15 @@ def build_epub2_with_pandoc(
       "encoding=UTF-8",
       "--standalone",
       "--split-level",
-      str(opts.chapter_level),
+      str(opts.split_level),
     ]
 
     if publisher:
       cmd.extend(["--metadata", f"publisher={publisher}"])
 
     if identifier:
-      cmd.extend(["--epub-metadata", str(identifier)])
+      # Keep identifier stable for Kindle.
+      cmd.extend(["--metadata", f"identifier={identifier}"])
 
     if opts.toc:
       cmd.extend(["--toc", "--toc-depth", str(opts.toc_depth)])
@@ -96,6 +119,22 @@ def build_epub2_with_pandoc(
     cmd.extend(["-o", str(out_path)])
     cmd.extend([str(p) for p in html_files])
 
-    subprocess.run(cmd, check=True)
+    proc = subprocess.run(
+      cmd,
+      stdout=subprocess.PIPE,
+      stderr=subprocess.PIPE,
+      text=True,
+    )
+
+    if proc.returncode != 0:
+      # On failure, always show stderr.
+      raise RuntimeError(f"pandoc failed (exit {proc.returncode}):\n{proc.stderr.strip()}")
+
+    if verbose and proc.stderr.strip():
+      print(proc.stderr.strip())
+    elif proc.stderr.strip():
+      summary = _summarize_pandoc_warnings(proc.stderr)
+      if summary:
+        print(summary)
 
   return out_path

{docs2epub-0.1.0 → docs2epub-0.1.2}/tests/test_smoke.py

@@ -16,8 +16,17 @@ def test_build_epub3_smoke(tmp_path):
 
 def test_kindle_cleaner_strips_tabindex_and_ol_start():
   cleaned = clean_html_for_kindle_epub2(
-    '<div tabindex="0"><ol start="2"><li><u>Hi</u></li></ol></div>'
+    '<div tabindex="0"><ol start="2"><li><u>Hi</u></li></ol></div>',
+    keep_images=False,
   )
   assert "tabindex" not in cleaned
   assert "start=" not in cleaned
   assert "underline" in cleaned
+
+
+def test_kindle_cleaner_drops_remote_images_by_default():
+  cleaned = clean_html_for_kindle_epub2(
+    '<p>x</p><img src="https://example.com/a.png" /><p>y</p>',
+    keep_images=False,
+  )
+  assert "img" not in cleaned

{docs2epub-0.1.0 → docs2epub-0.1.2}/uv.lock

@@ -166,7 +166,7 @@ wheels = [
 
 [[package]]
 name = "docs2epub"
-version = "0.1.0"
+version = "0.1.1"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },

docs2epub-0.1.0/src/docs2epub/cli.py

@@ -1,95 +0,0 @@
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from .docusaurus_next import DocusaurusNextOptions, iter_docusaurus_next
-from .epub import EpubMetadata, build_epub
-from .pandoc_epub2 import build_epub2_with_pandoc
-
-
-def _build_parser() -> argparse.ArgumentParser:
-  p = argparse.ArgumentParser(
-    prog="docs2epub",
-    description="Turn documentation sites into an EPUB (Kindle-friendly).",
-  )
-
-  p.add_argument(
-    "--start-url",
-    required=True,
-    help="Starting URL for scraping (initially: Docusaurus docs page).",
-  )
-  p.add_argument(
-    "--base-url",
-    default=None,
-    help="Base URL used to resolve relative links (defaults to start-url).",
-  )
-  p.add_argument("--max-pages", type=int, default=None)
-  p.add_argument("--sleep-s", type=float, default=0.5)
-
-  p.add_argument("--title", required=True)
-  p.add_argument("--author", required=True)
-  p.add_argument("--language", default="en")
-  p.add_argument("--identifier", default=None)
-  p.add_argument("--publisher", default=None)
-
-  p.add_argument(
-    "--format",
-    default="epub2",
-    choices=["epub2", "epub3"],
-    help="Output format. Default: epub2 (Kindle-friendly).",
-  )
-
-  p.add_argument(
-    "--out",
-    required=True,
-    help="Output EPUB file path.",
-  )
-
-  return p
-
-
-def main(argv: list[str] | None = None) -> int:
-  args = _build_parser().parse_args(argv)
-
-  options = DocusaurusNextOptions(
-    start_url=args.start_url,
-    base_url=args.base_url,
-    max_pages=args.max_pages,
-    sleep_s=args.sleep_s,
-  )
-
-  chapters = iter_docusaurus_next(options)
-  if not chapters:
-    raise SystemExit("No chapters scraped (did not find article content).")
-
-  out_path: Path
-
-  if args.format == "epub2":
-    out_path = build_epub2_with_pandoc(
-      chapters=chapters,
-      out_file=Path(args.out),
-      title=args.title,
-      author=args.author,
-      language=args.language,
-      publisher=args.publisher,
-      identifier=args.identifier,
-    )
-  else:
-    meta = EpubMetadata(
-      title=args.title,
-      author=args.author,
-      language=args.language,
-      identifier=args.identifier,
-      publisher=args.publisher,
-    )
-
-    out_path = build_epub(
-      chapters=chapters,
-      out_file=Path(args.out),
-      meta=meta,
-    )
-
-  print(f"Scraped {len(chapters)} pages")
-  print(f"EPUB written to: {out_path.resolve()}")
-  return 0