cppmanlite 0.1.0__tar.gz

cppmanlite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dive4dec
+
+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.

cppmanlite-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: cppmanlite
+Version: 0.1.0
+Summary: Lightweight serverless C++ documentation lookup — pure Python, no C deps
+License-Expression: MIT
+Project-URL: Homepage, https://dive4dec.github.io/cppmanlite/
+Project-URL: Repository, https://github.com/dive4dec/cppmanlite
+Keywords: cpp,cplusplus,cppreference,documentation,cppman
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# cppmanlite
+
+Lightweight serverless C++ documentation lookup — a pure Python package and
+static site powered by [cppreference.com](https://en.cppreference.com).
+
+## Features
+
+- **Pure Python** — no C dependencies, works in CPython, Pyodide, Jupyter
+- **Static site** — served from GitHub Pages or any static host
+- **Client-side search** — lunr.js fuzzy search over a ~1MB index
+- **On-demand page loading** — fetches from cppreference.com or local bundle
+- **Auto-updating** — GitHub Action refreshes the index monthly
+- **Kubernetes-ready** — Helm chart included for `/cppmanlite` route
+
+## Python package
+
+```bash
+pip install cppmanlite
+```
+
+```python
+import cppmanlite
+
+# Search for C++ documentation
+cppmanlite.search("vector")
+# [{'title': 'std::vector', 'url': 'cpp/container/vector.html', ...}, ...]
+
+# Display a page (renders HTML in Jupyter, plain text in terminal)
+cppmanlite.man("std::vector")
+
+# Alias
+cppmanlite.help("sort")
+```
+
+Works in [Pyodide](https://pyodide.org) (Python in the browser) — no compiled
+dependencies required.
+
+## Static site
+
+The `site/` directory contains a standalone search UI:
+
+- `index.html` — search box + results + page reader
+- `app.js` — lunr.js search + on-demand page fetching
+- `style.css` — dark/light theme
+
+Deployed to GitHub Pages at: **https://dive4dec.github.io/cppmanlite/**
+
+## Docker / Kubernetes
+
+```bash
+docker build -t cppmanlite:v1 .
+```
+
+Multi-stage build: downloads the cppreference HTML archive, strips boilerplate,
+builds a search index, and serves everything via nginx.
+
+```bash
+helm install cppmanlite ./chart -n cppmanlite
+```
+
+Serves at `https://socratic.cs.cityu.edu.hk/cppmanlite/`
+
+## How it works
+
+1. **Index building** (`scripts/build_index.py`): Downloads the cppreference
+   HTML book archive, extracts page titles + snippets, fixes relative URLs,
+   and writes a compact JSON index (~1.2MB for 6,000+ pages).
+
+2. **Search**: lunr.js builds a client-side full-text search index from the
+   JSON. Results show title, URL path, and a content snippet.
+
+3. **Page reading**: When a user clicks a result, the reader fetches the page
+   — either from a local `docs/` bundle (Docker/K8s deployment) or directly
+   from cppreference.com (GitHub Pages).
+
+4. **Auto-update**: A GitHub Action runs monthly, downloads the latest
+   cppreference archive, rebuilds the index, and deploys to GitHub Pages.
+
+## Data source
+
+Documentation from [cppreference.com](https://en.cppreference.com), licensed
+under CC-BY-SA 3.0 / GFDL. The HTML book archive is published by
+[PeterFeicht/cppreference-doc](https://github.com/PeterFeicht/cppreference-doc).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cppmanlite-0.1.0/README.md

@@ -0,0 +1,87 @@
+# cppmanlite
+
+Lightweight serverless C++ documentation lookup — a pure Python package and
+static site powered by [cppreference.com](https://en.cppreference.com).
+
+## Features
+
+- **Pure Python** — no C dependencies, works in CPython, Pyodide, Jupyter
+- **Static site** — served from GitHub Pages or any static host
+- **Client-side search** — lunr.js fuzzy search over a ~1MB index
+- **On-demand page loading** — fetches from cppreference.com or local bundle
+- **Auto-updating** — GitHub Action refreshes the index monthly
+- **Kubernetes-ready** — Helm chart included for `/cppmanlite` route
+
+## Python package
+
+```bash
+pip install cppmanlite
+```
+
+```python
+import cppmanlite
+
+# Search for C++ documentation
+cppmanlite.search("vector")
+# [{'title': 'std::vector', 'url': 'cpp/container/vector.html', ...}, ...]
+
+# Display a page (renders HTML in Jupyter, plain text in terminal)
+cppmanlite.man("std::vector")
+
+# Alias
+cppmanlite.help("sort")
+```
+
+Works in [Pyodide](https://pyodide.org) (Python in the browser) — no compiled
+dependencies required.
+
+## Static site
+
+The `site/` directory contains a standalone search UI:
+
+- `index.html` — search box + results + page reader
+- `app.js` — lunr.js search + on-demand page fetching
+- `style.css` — dark/light theme
+
+Deployed to GitHub Pages at: **https://dive4dec.github.io/cppmanlite/**
+
+## Docker / Kubernetes
+
+```bash
+docker build -t cppmanlite:v1 .
+```
+
+Multi-stage build: downloads the cppreference HTML archive, strips boilerplate,
+builds a search index, and serves everything via nginx.
+
+```bash
+helm install cppmanlite ./chart -n cppmanlite
+```
+
+Serves at `https://socratic.cs.cityu.edu.hk/cppmanlite/`
+
+## How it works
+
+1. **Index building** (`scripts/build_index.py`): Downloads the cppreference
+   HTML book archive, extracts page titles + snippets, fixes relative URLs,
+   and writes a compact JSON index (~1.2MB for 6,000+ pages).
+
+2. **Search**: lunr.js builds a client-side full-text search index from the
+   JSON. Results show title, URL path, and a content snippet.
+
+3. **Page reading**: When a user clicks a result, the reader fetches the page
+   — either from a local `docs/` bundle (Docker/K8s deployment) or directly
+   from cppreference.com (GitHub Pages).
+
+4. **Auto-update**: A GitHub Action runs monthly, downloads the latest
+   cppreference archive, rebuilds the index, and deploys to GitHub Pages.
+
+## Data source
+
+Documentation from [cppreference.com](https://en.cppreference.com), licensed
+under CC-BY-SA 3.0 / GFDL. The HTML book archive is published by
+[PeterFeicht/cppreference-doc](https://github.com/PeterFeicht/cppreference-doc).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cppmanlite-0.1.0/cppmanlite/__init__.py

@@ -0,0 +1,19 @@
+"""cppmanlite — lightweight serverless C++ documentation lookup.
+
+A pure-Python package for searching and displaying C++ documentation
+from cppreference.com.  Works in standard Python, Jupyter notebooks,
+and Pyodide (no C dependencies).
+
+Usage:
+    import cppmanlite
+    cppmanlite.search("vector")       # list matching pages
+    cppmanlite.man("std::vector")     # display a page
+    cppmanlite.help("sort")           # alias for search
+
+In Jupyter, results render as HTML with clickable links.
+"""
+
+from .core import search, man, help as help_query, list_pages, refresh_index
+
+__version__ = "0.1.0"
+__all__ = ["search", "man", "help_query", "list_pages", "refresh_index"]

cppmanlite-0.1.0/cppmanlite/core.py

@@ -0,0 +1,288 @@
+"""Core search and display logic for cppmanlite.
+
+No external dependencies — pure stdlib.  Fetches pages on-demand from
+cppreference.com when not bundled locally.
+
+Works in CPython, Jupyter, and Pyodide (browser).  In Pyodide, network
+fetches use the browser's Fetch API via pyodide.http instead of urllib.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+# --------------------------------------------------------------------------- #
+# Environment detection
+# --------------------------------------------------------------------------- #
+
+def _detect_pyodide() -> bool:
+    """Return True if running under Pyodide."""
+    try:
+        import sys
+        return "pyodide" in sys.modules or "pyodide" in getattr(sys, "platform", "")
+    except Exception:
+        return False
+
+
+_IS_PYODIDE = _detect_pyodide()
+
+
+# --------------------------------------------------------------------------- #
+# Network fetch — urllib in CPython, pyodide.http in Pyodide
+# --------------------------------------------------------------------------- #
+
+def _fetch_url(url: str, timeout: int = 15) -> str:
+    """Fetch a URL and return text.  Uses urllib (CPython) or pyfetch (Pyodide)."""
+    if _IS_PYODIDE:
+        return _fetch_pyodide(url)
+    return _fetch_urllib(url, timeout)
+
+
+def _fetch_urllib(url: str, timeout: int) -> str:
+    import urllib.request
+    req = urllib.request.Request(url, headers={"User-Agent": "cppmanlite/0.1"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.read().decode("utf-8", errors="replace")
+
+
+def _fetch_pyodide(url: str) -> str:
+    """Fetch via pyodide.http.pyfetch (async under the hood, but Pyodide
+    auto-awaits top-level coroutines)."""
+    from pyodide.http import pyfetch
+    resp = pyfetch(url, headers={"User-Agent": "cppmanlite/0.1"})
+    return resp.string
+
+
+# --------------------------------------------------------------------------- #
+# Index management
+# --------------------------------------------------------------------------- #
+
+_INDEX: list[dict[str, str]] = []
+_INDEX_PATH = Path(__file__).parent / "data" / "index.json"
+
+# When running in Pyodide the bundled index.json ships inside the wheel;
+# when running in CPython without the bundle, fetch from GitHub Pages.
+_INDEX_FALLBACK_URL = "https://dive4dec.github.io/cppmanlite/index.json"
+
+# cppreference page base URL (redirects /w/cpp/... → /cpp/...)
+_PAGE_BASE = "https://en.cppreference.com/w"
+
+
+def _load_index() -> list[dict[str, str]]:
+    """Load the search index, fetching it if necessary."""
+    global _INDEX
+    if _INDEX:
+        return _INDEX
+    if _INDEX_PATH.exists():
+        with open(_INDEX_PATH, encoding="utf-8") as f:
+            _INDEX = json.load(f)
+    else:
+        # Fetch from GitHub Pages (works in both CPython and Pyodide)
+        try:
+            _INDEX = json.loads(_fetch_url(_INDEX_FALLBACK_URL))
+        except Exception:
+            _INDEX = []
+    return _INDEX
+
+
+# ---------------------------------------------------------------------------
+# Search
+# ---------------------------------------------------------------------------
+
+
+def search(query: str, limit: int = 20) -> list[dict[str, str]]:
+    """Search C++ documentation pages.
+
+    Args:
+        query: Search term (e.g. "vector", "std::sort", "shared_ptr").
+        limit: Maximum number of results.
+
+    Returns:
+        List of dicts with keys: title, url, snippet.
+    """
+    idx = _load_index()
+    if not idx:
+        return []
+    q = query.lower().strip()
+    # Normalise std:: prefix
+    q_norm = re.sub(r"^std::", "", q)
+    results = []
+    for entry in idx:
+        title = entry.get("title", "").lower()
+        url = entry.get("url", "").lower()
+        # Score: exact match > starts with > contains in title > contains in URL
+        score = 0
+        if title == q or title == q_norm:
+            score = 100
+        elif title.startswith(q) or title.startswith(q_norm):
+            score = 80
+        elif q in title or q_norm in title:
+            score = 60
+        elif q in url or q_norm in url:
+            score = 40
+        if score > 0:
+            results.append({**entry, "_score": score})
+    results.sort(key=lambda x: (-x["_score"], x.get("title", "")))
+    return [{k: v for k, v in r.items() if k != "_score"} for r in results[:limit]]
+
+
+def list_pages(limit: int = 0) -> list[dict[str, str]]:
+    """List all indexed pages (for debugging/browsing)."""
+    idx = _load_index()
+    return idx if limit == 0 else idx[:limit]
+
+
+# ---------------------------------------------------------------------------
+# Page fetching and rendering
+# ---------------------------------------------------------------------------
+
+_CONTENT_RE = re.compile(
+    r'<div id="mw-content-text"[^>]*>(.*?)(?:</div>\s*<!--|\Z)',
+    re.DOTALL,
+)
+_SCRIPT_RE = re.compile(r"<script[^>]*>.*?</script>", re.DOTALL)
+_STYLE_RE = re.compile(r"<style[^>]*>.*?</style>", re.DOTALL)
+_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_EDIT_RE = re.compile(r'<span class="mw-editsection">.*?</span>', re.DOTALL)
+
+
+_NAVBAR_RE = re.compile(
+    r'<div class="t-navbar"[^>]*>.*?(?:</div>\s*(?=<div|<h[1-6]|<table|<p|\Z))',
+    re.DOTALL,
+)
+_NV_TABLE_RE = re.compile(r'<table class="t-nv-begin"[^>]*>.*?</table>', re.DOTALL)
+
+
+def _fetch_page(url: str) -> str:
+    """Fetch a cppreference page and extract the main content HTML."""
+    full_url = f"{_PAGE_BASE}/{url}" if not url.startswith("http") else url
+    html_raw = _fetch_url(full_url)
+    # Extract #mw-content-text
+    m = _CONTENT_RE.search(html_raw)
+    if not m:
+        return "<p>Could not extract page content.</p>"
+    content = m.group(1)
+    # Clean up
+    content = _SCRIPT_RE.sub("", content)
+    content = _STYLE_RE.sub("", content)
+    content = _COMMENT_RE.sub("", content)
+    content = _EDIT_RE.sub("", content)
+    # Strip residual [edit] markers left by mw-editsection removal
+    content = re.sub(r"\[edit\]", "", content)
+    # Strip cppreference navigation chrome (t-navbar, t-nv-begin tables)
+    content = _NAVBAR_RE.sub("", content)
+    content = _NV_TABLE_RE.sub("", content)
+    # Fix relative URLs
+    content = re.sub(r'href="/w/', 'href="https://en.cppreference.com/w/', content)
+    content = re.sub(r'src="/', 'src="https://en.cppreference.com/', content)
+    return content
+
+
+# ---------------------------------------------------------------------------
+# Display
+# ---------------------------------------------------------------------------
+
+
+def _is_jupyter() -> bool:
+    try:
+        from IPython.display import HTML, display  # noqa: F401
+
+        get_ipython  # type: ignore[name-defined]
+        return True
+    except Exception:
+        return False
+
+
+def _format_search_html(results: list[dict[str, str]]) -> str:
+    rows = []
+    for r in results:
+        title = html.escape(r.get("title", ""))
+        url = html.escape(r.get("url", ""))
+        snippet = html.escape(r.get("snippet", ""))[:120]
+        rows.append(
+            f'<tr><td><a href="https://en.cppreference.com/w/{url}" '
+            f'target="_blank">{title}</a></td>'
+            f'<td><code>{snippet}</code></td></tr>'
+        )
+    return (
+        '<table style="font-size:14px;border-collapse:collapse">'
+        "<tr><th>Title</th><th>Path</th></tr>"
+        + "\n".join(rows)
+        + "</table>"
+    )
+
+
+def _format_page_html(content: str) -> str:
+    return (
+        '<div style="max-height:600px;overflow:auto;'
+        'border:1px solid #ddd;padding:16px;font-size:14px">'
+        + content
+        + "</div>"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def man(query: str) -> Any:
+    """Display a C++ documentation page (like ``man`` for C++).
+
+    In Jupyter: renders HTML inline.
+    In terminal: prints plain text.
+
+    Args:
+        query: Page title or URL path (e.g. "std::vector" or "cpp/container/vector").
+    """
+    results = search(query, limit=1)
+    if not results:
+        msg = f"No documentation found for '{query}'."
+        if _is_jupyter():
+            from IPython.display import HTML, display
+
+            display(HTML(f"<p>{html.escape(msg)}</p>"))
+        print(msg)
+        return
+    url = results[0]["url"]
+    content = _fetch_page(url)
+    if _is_jupyter():
+        from IPython.display import HTML, display
+
+        display(HTML(_format_page_html(content)))
+    else:
+        # Strip HTML tags for terminal, then decode entities
+        text = re.sub(r"<[^>]+>", "", content)
+        text = html.unescape(text)
+        text = re.sub(r"\[edit\]", "", text)
+        text = re.sub(r"\s+", " ", text).strip()
+        print(text[:4000])
+
+
+def help(query: str) -> Any:
+    """Search C++ documentation (alias for :func:`search`).
+
+    Args:
+        query: Search term.
+    """
+    return search(query)
+
+
+def refresh_index() -> int:
+    """Re-download the search index from GitHub Pages.
+
+    Returns the number of indexed pages.
+    """
+    global _INDEX
+    _INDEX = []
+    url = "https://dive4dec.github.io/cppmanlite/index.json"
+    _INDEX = json.loads(_fetch_url(url))
+    return len(_INDEX)
+
+
+# Re-export ``help`` under a safe alias to avoid shadowing builtin
+help_query = help