PyPI - docs-site - Versions diffs - 0.1.1__py3-none-any.whl - Mend

docs-site 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

docs_site/__init__.py +5 -0
docs_site/__main__.py +4 -0
docs_site/cli.py +59 -0
docs_site/html_processing.py +123 -0
docs_site/manifest.py +111 -0
docs_site/pdf_processing.py +69 -0
docs_site/py.typed +0 -0
docs_site/site_builder.py +73 -0
docs_site/static/css/content.css +91 -0
docs_site/static/css/shell.css +279 -0
docs_site/static/js/content-dark-listener.js +17 -0
docs_site/static/js/shell.js +333 -0
docs_site/templates/shell.html.jinja +35 -0
docs_site/templates/welcome.html.jinja +22 -0
docs_site/types.py +17 -0
docs_site/utils.py +27 -0
docs_site-0.1.1.dist-info/METADATA +95 -0
docs_site-0.1.1.dist-info/RECORD +22 -0
docs_site-0.1.1.dist-info/WHEEL +5 -0
docs_site-0.1.1.dist-info/entry_points.txt +2 -0
docs_site-0.1.1.dist-info/licenses/LICENSE +21 -0
docs_site-0.1.1.dist-info/top_level.txt +1 -0

docs_site/__init__.py ADDED Viewed

@@ -0,0 +1,5 @@
+"""docs_site, turn a folder of HTML + PDF files into a searchable local doc site."""
+from .site_builder import build_site
+__all__ = ["build_site"]

docs_site/__main__.py ADDED Viewed

@@ -0,0 +1,4 @@
+from .cli import main
+if __name__ == "__main__":
+    raise SystemExit(main())

docs_site/cli.py ADDED Viewed

@@ -0,0 +1,59 @@
+"""Command-line entry point: `docs-site /path/to/folder`."""
+import argparse
+import sys
+import webbrowser
+from pathlib import Path
+from .site_builder import build_site
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="docs-site",
+        description="Build a searchable local doc site from a folder of HTML + PDF files.",
+    )
+    parser.add_argument(
+        "folder",
+        type=Path,
+        help="Folder to scan (recursively) for .html/.htm/.pdf files",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help="Output directory (default: <folder>/_site)",
+    )
+    parser.add_argument(
+        "--no-open",
+        action="store_true",
+        help="Don't open the site in a browser after building",
+    )
+    args = parser.parse_args(argv)
+    root = args.folder.resolve()
+    if not root.is_dir():
+        print(f"error: not a folder: {root}", file=sys.stderr)
+        return 1
+    output_dir = (args.output or root / "_site").resolve()
+    manifest = build_site(root, output_dir, site_title=root.name)
+    n_html = sum(1 for f in manifest["files"] if f["type"] == "html")
+    n_pdf = sum(1 for f in manifest["files"] if f["type"] == "pdf")
+    print(f"Indexed {n_html} HTML file(s) and {n_pdf} PDF file(s).")
+    print(f"Site written to: {output_dir}")
+    if not manifest["files"]:
+        print(f"(No .html/.htm/.pdf files found under {root})")
+    if not args.no_open:
+        webbrowser.open((output_dir / "index.html").as_uri())
+    return 0
+if __name__ == "__main__":
+    sys.exit(main())

docs_site/html_processing.py ADDED Viewed

@@ -0,0 +1,123 @@
+"""Everything needed to turn one arbitrary HTML file into a processed content page."""
+import re
+from pathlib import Path
+from typing import TypedDict
+from bs4 import BeautifulSoup
+from .types import Heading
+from .utils import slugify
+HTML_TAG_RE = re.compile(r"<html[\s>]", re.IGNORECASE)
+HEAD_TAG_RE = re.compile(r"<head[\s>]", re.IGNORECASE)
+BODY_TAG_RE = re.compile(r"<body[\s>]", re.IGNORECASE)
+HEAD_CLOSE_RE = re.compile(r"</head>", re.IGNORECASE)
+HTML_OPEN_RE = re.compile(r"(<html[^>]*>)", re.IGNORECASE)
+HTML_CLOSE_RE = re.compile(r"(</html>)", re.IGNORECASE)
+HEADING_TAG_RE = re.compile(r"^h[1-6]$")
+# Relative path (from output/pages/*.html) to the shared frontend static assets.
+CONTENT_CSS_HREF = "../static/css/content.css"
+CONTENT_DARK_LISTENER_SRC = "../static/js/content-dark-listener.js"
+class HtmlPageResult(TypedDict):
+    html: str
+    title: str
+    headings: list[Heading]
+    text: str
+def ensure_full_document(document: str, title: str) -> str:
+    """Wrap a bare HTML fragment into a full <html><head><body> document.
+    Leaves already-complete documents untouched; fills in only whichever of
+    <html>/<head>/<body> is missing.
+    """
+    if not HTML_TAG_RE.search(document):
+        return (
+            "<!DOCTYPE html>\n<html>\n<head>\n"
+            '<meta charset="utf-8">\n'
+            f"<title>{title}</title>\n"
+            "</head>\n<body>\n"
+            f"{document}\n"
+            "</body>\n</html>"
+        )
+    if not HEAD_TAG_RE.search(document):
+        document = HTML_OPEN_RE.sub(
+            r"\1\n<head>\n"
+            '<meta charset="utf-8">\n'
+            f"<title>{title}</title>\n"
+            "</head>",
+            document,
+            count=1,
+        )
+    if not BODY_TAG_RE.search(document):
+        if HEAD_CLOSE_RE.search(document):
+            document = HEAD_CLOSE_RE.sub(r"\g<0>\n<body>", document, count=1)
+        else:
+            document = HTML_OPEN_RE.sub(r"\1\n<body>", document, count=1)
+        document = HTML_CLOSE_RE.sub("</body>\n\\1", document, count=1)
+    return document
+def process_html_file(path: Path) -> HtmlPageResult:
+    """Parse, wrap-if-needed, id-tag headings, and link in the reader stylesheet/script."""
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    raw = ensure_full_document(raw, title=path.stem)
+    soup = BeautifulSoup(raw, "html.parser")
+    html_tag = soup.html
+    if html_tag is None:
+        # Extremely malformed input; fall back to a minimal shell around it.
+        soup = BeautifulSoup(ensure_full_document(str(soup), path.stem), "html.parser")
+        html_tag = soup.html
+    if html_tag is None:
+        # ensure_full_document() always produces a top-level <html>
+        raise ValueError(f"could not construct a valid <html> root for {path}")
+    head_tag = soup.head
+    if head_tag is None:
+        head_tag = soup.new_tag("head")
+        html_tag.insert(0, head_tag)
+    body_tag = soup.body
+    if body_tag is None:
+        body_tag = soup.new_tag("body")
+        html_tag.append(body_tag)
+    title = path.stem
+    if soup.title and soup.title.string and soup.title.string.strip():
+        title = soup.title.string.strip()
+    used_ids = {tag.get("id") for tag in soup.find_all(id=True) if tag.get("id")}
+    headings: list[Heading] = []
+    for tag in soup.find_all(HEADING_TAG_RE):
+        text = tag.get_text(strip=True)
+        if not text:
+            continue
+        hid = tag.get("id")
+        if not hid:
+            hid = slugify(text, used_ids)
+            tag["id"] = hid
+        else:
+            used_ids.add(hid)
+        headings.append({"level": int(tag.name[1]), "id": str(hid), "text": text})
+    plain_text = soup.get_text(separator=" ", strip=True)
+    link_tag = soup.new_tag("link", rel="stylesheet", href=CONTENT_CSS_HREF)
+    head_tag.append(link_tag)
+    script_tag = soup.new_tag("script", src=CONTENT_DARK_LISTENER_SRC)
+    body_tag.append(script_tag)
+    return {
+        "html": str(soup),
+        "title": title,
+        "headings": headings,
+        "text": plain_text,
+    }

docs_site/manifest.py ADDED Viewed

@@ -0,0 +1,111 @@
+"""Scan a folder for HTML/PDF files and build the JSON manifest the frontend reads."""
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Literal, TypedDict
+from .html_processing import process_html_file
+from .pdf_processing import process_pdf_file
+from .types import Heading
+from .utils import safe_id
+INDEXABLE_SUFFIXES = (".html", ".htm", ".pdf")
+# Per-file cap on indexed text so the manifest can't explode on huge PDFs.
+MAX_INDEXED_CHARS = 400_000
+@dataclass
+class ManifestEntry:
+    """One indexed file, in the shape the frontend's JS expects (see
+    static/js/shell.js). `page_count` is only meaningful for PDFs but is
+    always present so the JSON shape is uniform across entries.
+    """
+    id: str
+    type: Literal["html", "pdf"]
+    title: str
+    relpath: str
+    src: str
+    headings: list[Heading] = field(default_factory=list)
+    text: str = ""
+    page_count: int | None = None
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+class Manifest(TypedDict):
+    files: list[dict[str, Any]]
+def scan_folder(root: Path, output_dir: Path) -> list[Path]:
+    """Recursively find all indexable files under root, skipping the output dir itself."""
+    files = []
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        try:
+            p.relative_to(output_dir)
+            continue  # already inside the generated site — don't re-index it
+        except ValueError:
+            pass
+        if p.suffix.lower() in INDEXABLE_SUFFIXES:
+            files.append(p)
+    return files
+def build_manifest(root: Path, files: list[Path], pages_dir: Path) -> Manifest:
+    """Process every file, write out HTML content pages, and return the site manifest."""
+    manifest_entries: list[ManifestEntry] = []
+    used_ids: set[str] = set()
+    for path in files:
+        relpath = path.relative_to(root).as_posix()
+        fid = safe_id(relpath, used_ids)
+        suffix = path.suffix.lower()
+        entry: ManifestEntry
+        if suffix in (".html", ".htm"):
+            try:
+                html_result = process_html_file(path)
+            except Exception as exc:  # noqa: BLE001 - keep building the rest of the site
+                print(f"warning: skipping {relpath} ({exc})")
+                continue
+            out_path = pages_dir / f"{fid}.html"
+            out_path.write_text(html_result["html"], encoding="utf-8")
+            entry = ManifestEntry(
+                id=fid,
+                type="html",
+                title=html_result["title"],
+                relpath=relpath,
+                src=f"pages/{out_path.name}",
+                headings=html_result["headings"],
+                text=html_result["text"][:MAX_INDEXED_CHARS],
+            )
+        elif suffix == ".pdf":
+            try:
+                pdf_result = process_pdf_file(path)
+            except Exception as exc:  # noqa: BLE001
+                print(f"warning: skipping {relpath} ({exc})")
+                continue
+            # Reference the original PDF in place rather than duplicating it.
+            src = (Path("..") / path.relative_to(root)).as_posix()
+            entry = ManifestEntry(
+                id=fid,
+                type="pdf",
+                title=pdf_result["title"],
+                relpath=relpath,
+                src=src,
+                headings=pdf_result["headings"],
+                text=pdf_result["text"][:MAX_INDEXED_CHARS],
+                page_count=pdf_result["page_count"],
+            )
+        else:
+            continue
+        manifest_entries.append(entry)
+    manifest_entries.sort(key=lambda e: e.relpath.lower())
+    return {"files": [e.to_dict() for e in manifest_entries]}

docs_site/pdf_processing.py ADDED Viewed

@@ -0,0 +1,69 @@
+"""Everything needed to index one PDF file (no rendering, the browser's
+native PDF viewer handles that inside the iframe)."""
+from pathlib import Path
+from typing import Any, TypedDict
+from pypdf import PdfReader
+from pypdf.errors import PyPdfError
+from .types import Heading
+class PdfResult(TypedDict):
+    title: str
+    headings: list[Heading]
+    text: str
+    page_count: int
+def _extract_headings(
+    reader: PdfReader, outline: list[Any], level: int = 1
+) -> list[Heading]:
+    headings: list[Heading] = []
+    for item in outline:
+        if isinstance(item, list):
+            headings.extend(_extract_headings(reader, item, level + 1))
+        else:
+            try:
+                page_num = reader.get_destination_page_number(item)
+                title = getattr(item, "title", "") or ""
+                if page_num is not None and title.strip():
+                    headings.append(
+                        {"level": level, "page": page_num + 1, "text": title.strip()}
+                    )
+            except (PyPdfError, AttributeError, TypeError, ValueError):
+                continue
+    return headings
+def process_pdf_file(path: Path) -> PdfResult:
+    reader = PdfReader(str(path))
+    metadata = reader.metadata
+    raw_title = metadata.title if metadata else ""
+    title = raw_title.strip() if raw_title else path.stem
+    try:
+        outline = reader.outline or []
+        headings = _extract_headings(reader, outline)
+    except (PyPdfError, AttributeError, TypeError, ValueError):
+        headings = []
+    page_count = len(reader.pages)
+    text_chunks: list[str] = []
+    for page in reader.pages:
+        try:
+            page_text = page.extract_text()
+            if page_text:
+                text_chunks.append(page_text)
+        except (PyPdfError, AttributeError, TypeError, ValueError):
+            continue
+    plain_text = " ".join(text_chunks)
+    return {
+        "title": title,
+        "headings": headings,
+        "text": plain_text,
+        "page_count": page_count,
+    }

docs_site/py.typed ADDED Viewed

File without changes

docs_site/site_builder.py ADDED Viewed

@@ -0,0 +1,73 @@
+"""Ties scanning/processing (manifest.py) together with the frontend
+templates/static assets to produce a finished, browsable site directory.
+This is the only module that knows about output paths and templates,
+manifest.py and the processors know nothing about how the result gets
+rendered, and the templates/static/ files know nothing about Python.
+"""
+import json
+import shutil
+from importlib import resources
+from pathlib import Path
+from jinja2 import Environment, FileSystemLoader
+from .manifest import Manifest, build_manifest, scan_folder
+try:  # Python 3.11+
+    from importlib.resources.abc import Traversable
+except ImportError:  # Python 3.9 / 3.10
+    from importlib.abc import Traversable  # type: ignore[no-redef,attr-defined]
+def _package_path(*parts: str) -> Traversable:
+    return resources.files("docs_site").joinpath(*parts)
+def _copy_static_assets(output_dir: Path) -> None:
+    static_src = _package_path("static")
+    with resources.as_file(static_src) as static_path:
+        shutil.copytree(static_path, output_dir / "static", dirs_exist_ok=True)
+def _jinja_env() -> Environment:
+    templates_src = _package_path("templates")
+    with resources.as_file(templates_src) as templates_path:
+        # FileSystemLoader needs a real, stable directory; as_file guarantees
+        # one exists for the lifetime of this call even from a zipped install.
+        return Environment(
+            loader=FileSystemLoader(str(templates_path)),
+            autoescape=False,  # we control every template; manifest JSON must stay raw
+        )
+def build_site(root: Path, output_dir: Path, site_title: str) -> Manifest:
+    """Scan `root`, build the manifest, render the site into `output_dir`.
+    Returns the manifest (handy for callers that want summary stats).
+    """
+    pages_dir = output_dir / "pages"
+    pages_dir.mkdir(parents=True, exist_ok=True)
+    files = scan_folder(root, output_dir)
+    manifest = build_manifest(root, files, pages_dir)
+    _copy_static_assets(output_dir)
+    env = _jinja_env()
+    welcome_html = env.get_template("welcome.html.jinja").render(
+        count_files=len(manifest["files"])
+    )
+    (pages_dir / "_welcome.html").write_text(welcome_html, encoding="utf-8")
+    manifest_json = json.dumps(manifest, ensure_ascii=False).replace("</", "<\\/")
+    shell_html = env.get_template("shell.html.jinja").render(
+        site_title=site_title,
+        welcome_file="_welcome.html",
+        manifest_json=manifest_json,
+    )
+    (output_dir / "index.html").write_text(shell_html, encoding="utf-8")
+    return manifest

docs_site/static/css/content.css ADDED Viewed

@@ -0,0 +1,91 @@
+:root {
+  --bg: #ffffff;
+  --fg: #1a1a1a;
+  --muted: #6b6b6b;
+  --accent: #2563eb;
+  --border: #e2e2e2;
+  --code-bg: #f2f2f3;
+}
+html.reader-dark {
+  --bg: #1a1a1a;
+  --fg: #e6e6e6;
+  --muted: #a0a0a0;
+  --accent: #60a5fa;
+  --border: #3a3a3a;
+  --code-bg: #2a2a2a;
+}
+html,
+body {
+  background: var(--bg);
+  color: var(--fg);
+}
+body {
+  box-sizing: border-box;
+  margin: 0 auto;
+  max-width: 760px;
+  padding: 2.5rem 2rem 6rem;
+  font-family: Georgia, "Times New Roman", serif;
+  line-height: 1.7;
+  font-size: 18px;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  line-height: 1.3;
+  scroll-margin-top: 1.5rem;
+}
+p,
+ul,
+ol,
+blockquote {
+  margin: 0 0 1.1em 0;
+}
+a {
+  color: var(--accent);
+}
+img {
+  max-width: 100%;
+  height: auto;
+}
+pre,
+code {
+  background: var(--code-bg);
+  border-radius: 4px;
+  font-family: "Fira Code", Consolas, monospace;
+  font-size: 15px;
+}
+pre {
+  padding: 1em;
+  overflow-x: auto;
+}
+code {
+  padding: 0.15em 0.35em;
+}
+pre code {
+  padding: 0;
+  background: none;
+}
+blockquote {
+  border-left: 3px solid var(--border);
+  margin-left: 0;
+  padding-left: 1em;
+  color: var(--muted);
+}
+table {
+  border-collapse: collapse;
+  width: 100%;
+}
+th,
+td {
+  border: 1px solid var(--border);
+  padding: 0.5em 0.75em;
+  text-align: left;
+}
+mark {
+  background: #fde68a;
+  color: #1a1a1a;
+  border-radius: 2px;
+}