nvim-doc-reader 0.1.0__py3-none-any.whl

doc_reader/__init__.py

@@ -0,0 +1 @@
+"""doc-reader: keyboard-driven HTML reader for Markdown, with Neovim jumps."""

doc_reader/cli.py

@@ -0,0 +1,109 @@
+"""`docread` (serve, url, section, nvim-path) and `nvimd`."""
+import argparse
+import os
+import sys
+from importlib import resources
+
+from doc_reader import config, model
+from doc_reader.urls import Roots
+
+
+def _read(path, use_stdin):
+  if use_stdin:
+    return sys.stdin.read()
+  with open(path, encoding="utf-8") as f:
+    return f.read()
+
+
+def cmd_serve(cfg, args):
+  from doc_reader import serve  # aiohttp only when serving
+  serve.serve(cfg)
+
+
+def cmd_url(cfg, args):
+  """The reader URL of the section containing `line` -- computed from the
+  buffer text when it is piped in, so unsaved edits are accounted for."""
+  url = Roots(cfg.roots).url_path(args.path)
+  if url is None:
+    print(f"{args.path} is not under any root: {sorted(cfg.roots)}",
+          file=sys.stderr)
+    return 1
+  sec = model.section_at(model.parse(_read(args.path, args.stdin)), args.line)
+  print(cfg.base_url + url + (f"#{sec.id}" if sec else ""))
+  return 0
+
+
+def cmd_section(cfg, args):
+  """The 1-based line of section `id` in the text (stdin or file), or exit 1."""
+  line = model.line_of(model.parse(_read(args.path, args.stdin)), args.id)
+  if line is None:
+    return 1
+  print(line)
+  return 0
+
+
+def cmd_nvim_path(cfg, args):
+  print(resources.files("doc_reader").joinpath("nvim"))
+  return 0
+
+
+def cmd_install_skill(cfg, args):
+  """Copy the bundled agent skill(s) into a skills directory."""
+  dest = os.path.expanduser(args.dir)
+  src = resources.files("doc_reader").joinpath("skills")
+  for skill in src.iterdir():
+    if not skill.is_dir():
+      continue
+    os.makedirs(os.path.join(dest, skill.name), exist_ok=True)
+    for f in skill.iterdir():
+      out = os.path.join(dest, skill.name, f.name)
+      with open(out, "w", encoding="utf-8") as fh:
+        fh.write(f.read_text(encoding="utf-8"))
+      print(out)
+  return 0
+
+
+def main(argv=None):
+  p = argparse.ArgumentParser(prog="docread", description=__doc__)
+  p.add_argument("--config", help="config file (default: $DOCREADER_CONFIG or "
+                 "$XDG_CONFIG_HOME/doc-reader/config.toml)")
+  sub = p.add_subparsers(dest="cmd", required=True)
+  s = sub.add_parser("serve", help="run the reader server")
+  s.add_argument("--port", type=int)
+  s.add_argument("--bind")
+  s.add_argument("--root", action="append", metavar="NAME=DIR",
+                 help="replace the configured roots (repeatable)")
+  s.set_defaults(fn=cmd_serve)
+  s = sub.add_parser("url", help="reader URL for a file and line")
+  s.add_argument("path")
+  s.add_argument("line", type=int, nargs="?", default=1)
+  s.add_argument("--stdin", action="store_true", help="read the text from stdin")
+  s.set_defaults(fn=cmd_url)
+  s = sub.add_parser("section", help="line of a section id")
+  s.add_argument("path")
+  s.add_argument("id")
+  s.add_argument("--stdin", action="store_true")
+  s.set_defaults(fn=cmd_section)
+  s = sub.add_parser("nvim-path", help="directory to add to Neovim's runtimepath")
+  s.set_defaults(fn=cmd_nvim_path)
+  s = sub.add_parser("install-skill",
+                     help="install the doc-authoring agent skill")
+  s.add_argument("--dir", default="~/.claude/skills",
+                 help="skills directory (default: ~/.claude/skills)")
+  s.set_defaults(fn=cmd_install_skill)
+  args = p.parse_args(argv)
+  overrides = {"port": getattr(args, "port", None),
+               "bind": getattr(args, "bind", None)}
+  if getattr(args, "root", None):
+    overrides["roots"] = config.parse_roots(":".join(args.root))
+  cfg = config.load(args.config, overrides=overrides)
+  return args.fn(cfg, args) or 0
+
+
+def nvimd_main(argv=None):
+  from doc_reader import nvim
+  return nvim.nvimd(config.load(), sys.argv[1:] if argv is None else argv)
+
+
+if __name__ == "__main__":
+  sys.exit(main())

doc_reader/config.py

@@ -0,0 +1,124 @@
+"""Settings: defaults, then the TOML file, then DOCREADER_* env, then CLI flags.
+
+Nothing here names a host or a directory of ours. The defaults are the
+generic ones (XDG dirs, the home directory as the only root), and a site
+config supplies the rest.
+"""
+import os
+import pwd
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+  import tomllib
+else:
+  import tomli as tomllib
+
+
+def _xdg(var, fallback):
+  return os.environ.get(var) or os.path.expanduser(fallback)
+
+
+def _runtime_dir():
+  if os.environ.get("XDG_RUNTIME_DIR"):
+    return os.environ["XDG_RUNTIME_DIR"]
+  run = f"/run/user/{os.getuid()}"
+  return run if os.path.isdir(run) else "/tmp"
+
+
+def default_socket_glob():
+  """Where Neovim puts the socket it opens on startup: its stdpath("run"),
+  which is $XDG_RUNTIME_DIR or else a private random directory under the
+  temp dir (e.g. /tmp/nvim.root/8CVDuf/nvim.3950.0)."""
+  if os.environ.get("XDG_RUNTIME_DIR"):
+    return os.path.join(os.environ["XDG_RUNTIME_DIR"], "nvim.*.0")
+  user = pwd.getpwuid(os.getuid()).pw_name
+  return os.path.join(tempfile.gettempdir(), f"nvim.{user}", "*", "nvim.*.0")
+
+
+def expand(value):
+  """`~` and `$VAR`, with the XDG vars filled in when the environment lacks
+  them, so `$XDG_STATE_HOME/...` never expands to a path starting at `/`."""
+  env = dict(os.environ)
+  env.setdefault("XDG_CONFIG_HOME", _xdg("XDG_CONFIG_HOME", "~/.config"))
+  env.setdefault("XDG_STATE_HOME", _xdg("XDG_STATE_HOME", "~/.local/state"))
+  env.setdefault("XDG_RUNTIME_DIR", _runtime_dir())
+  out = os.path.expanduser(str(value))
+  for k in sorted(env, key=len, reverse=True):
+    out = out.replace("${" + k + "}", env[k]).replace("$" + k, env[k])
+  return out
+
+
+@dataclass
+class Config:
+  roots: dict = field(default_factory=lambda: {"home": os.path.expanduser("~")})
+  bind: str = "0.0.0.0"
+  port: int = 8765
+  public_url: str = ""
+  nvim: str = "nvim"
+  nvim_socket_glob: str = ""  # empty: default_socket_glob()
+  state_file: str = "$XDG_STATE_HOME/doc-reader/last"
+  poll_interval_s: float = 0.5
+
+  @property
+  def base_url(self):
+    return (self.public_url or f"http://localhost:{self.port}").rstrip("/")
+
+
+SCALARS = {"bind": str, "port": int, "public_url": str, "nvim": str,
+           "nvim_socket_glob": str,
+           "state_file": str, "poll_interval_s": float}
+
+
+def config_path():
+  if os.environ.get("DOCREADER_CONFIG"):
+    return Path(expand(os.environ["DOCREADER_CONFIG"]))
+  return Path(expand("$XDG_CONFIG_HOME/doc-reader/config.toml"))
+
+
+def parse_roots(spec):
+  """`name=/dir:name=/dir` (the DOCREADER_ROOTS form)."""
+  roots = {}
+  for part in filter(None, spec.split(":")):
+    name, sep, path = part.partition("=")
+    if not sep or not name or not path:
+      raise ValueError(f"bad root {part!r}: expected name=/dir")
+    roots[name] = path
+  return roots
+
+
+def load(path=None, env=None, overrides=None):
+  env = os.environ if env is None else env
+  cfg = Config()
+  path = Path(path) if path else config_path()
+  data = {}
+  if path.exists():
+    with open(path, "rb") as f:
+      data = tomllib.load(f)
+  unknown = set(data) - set(SCALARS) - {"roots"}
+  if unknown:
+    raise ValueError(f"{path}: unknown keys {sorted(unknown)}")
+  for key, kind in SCALARS.items():
+    if key in data:
+      setattr(cfg, key, kind(data[key]))
+    if env.get(f"DOCREADER_{key.upper()}"):
+      setattr(cfg, key, kind(env[f"DOCREADER_{key.upper()}"]))
+  if "roots" in data:
+    if not isinstance(data["roots"], dict):
+      raise ValueError(f"{path}: [roots] must be a table of name = \"/dir\"")
+    cfg.roots = dict(data["roots"])
+  if env.get("DOCREADER_ROOTS"):
+    cfg.roots = parse_roots(env["DOCREADER_ROOTS"])
+  for key, value in (overrides or {}).items():
+    if value is not None:
+      setattr(cfg, key, value)
+  for name in cfg.roots:
+    if "/" in name or not name:
+      raise ValueError(f"root name {name!r} must be a single path segment")
+  cfg.roots = {k: os.path.realpath(expand(v)) for k, v in cfg.roots.items()}
+  cfg.nvim_socket_glob = (expand(cfg.nvim_socket_glob) if cfg.nvim_socket_glob
+                          else default_socket_glob())
+  cfg.state_file = os.path.abspath(expand(cfg.state_file))
+  return cfg

doc_reader/model.py

@@ -0,0 +1,281 @@
+"""One parse of a Markdown document: sections, their IDs and source lines, and
+the HTML, all from the same markdown-it token stream.
+
+Everything that needs to know where a section is -- the page, `docread url`,
+the jump into Neovim -- goes through `parse`, so the browser and the editor
+can never disagree about what counts as a heading. A `#` line in a fenced
+code block is not one; a Setext heading is; a heading inside a list item or a
+blockquote renders but is not a section (it cannot hold nested content).
+"""
+import copy
+import re
+from dataclasses import dataclass, field
+
+from markdown_it import MarkdownIt
+from markdown_it.common.utils import escapeHtml
+from markdown_it.renderer import RendererHTML
+from markdown_it.token import Token
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+from mdit_py_plugins.front_matter import front_matter_plugin
+
+# A trailing `{#id}` on a heading. The attrs plugin in mdit-py-plugins 0.3
+# does not handle it, so this is a core rule of our own that edits the parsed
+# inline token -- never the source text, which would shift line numbers.
+EXPLICIT_ID_RE = re.compile(r"\s*\{#([A-Za-z][\w:.-]*)\}\s*$")
+# pm-tui's own task-row pattern (project_manager_tui/core.py parse_tasks).
+TASK_RE = re.compile(r"^(\d+)\.\s+\[([^\]])\]\s*(.*)$")
+
+
+@dataclass
+class Section:
+  id: str
+  level: int
+  title: str
+  line: int            # 1-based line of the heading
+  end: int             # 1-based last line of the section, children included
+  parent: "Section" = None
+  children: list = field(default_factory=list)
+
+
+@dataclass
+class Doc:
+  text: str
+  tokens: list
+  sections: list       # document order
+  warnings: list
+
+  @property
+  def title(self):
+    return self.sections[0].title if self.sections else ""
+
+
+def _explicit_ids(state):
+  tokens = state.tokens
+  for i, tok in enumerate(tokens):
+    if tok.type != "heading_open":
+      continue
+    inline = tokens[i + 1]
+    m = EXPLICIT_ID_RE.search(inline.content)
+    if not m or not inline.children or inline.children[-1].type != "text":
+      continue
+    last = inline.children[-1]
+    m_last = EXPLICIT_ID_RE.search(last.content)
+    if not m_last:
+      continue
+    last.content = last.content[:m_last.start()]
+    inline.content = inline.content[:m.start()]
+    tok.meta["explicit_id"] = m.group(1)
+
+
+def make_markdown():
+  md = (MarkdownIt("commonmark", {"html": False})
+        .enable(["table", "strikethrough"])
+        .use(front_matter_plugin)
+        # double_inline: a `$$...$$` written inside a paragraph (no blank line
+        # around it) is display math too, not `$` + inline math + `$`.
+        .use(dollarmath_plugin, double_inline=True))
+  md.core.ruler.after("inline", "explicit_heading_ids", _explicit_ids)
+  for name, display in (("math_inline", False), ("math_inline_double", True)):
+    md.add_render_rule(name, _math_span(display))
+  for name in ("math_block", "math_block_label"):
+    md.add_render_rule(name, _math_div)
+  md.add_render_rule("fence", _fence)
+  md.add_render_rule("link_open", _link_open)
+  md.add_render_rule("image", _image)
+  md.add_render_rule("list_item_open", _list_item_open)
+  return md
+
+
+def slug(text):
+  """GitHub's heading anchor: lowercase, drop punctuation other than `-` and
+  `_`, spaces to `-`."""
+  return re.sub(r"[^\w\- ]", "", text.strip().lower()).replace(" ", "-")
+
+
+def _plain(inline):
+  return "".join(c.content for c in inline.children or []
+                 if c.type in ("text", "code_inline", "math_inline",
+                               "math_inline_double")).strip()
+
+
+def parse(text):
+  tokens = _MD.parse(text)
+  heads = []
+  for i, tok in enumerate(tokens):
+    if tok.type == "heading_open" and tok.level == 0 and tok.map:
+      heads.append((tok, tokens[i + 1]))
+
+  warnings, used = [], set()
+  explicit = [tok.meta.get("explicit_id") for tok, _ in heads]
+  for eid in filter(None, explicit):
+    if eid in used:
+      warnings.append(f"duplicate section id #{eid}")
+    used.add(eid)
+
+  def unique(base):
+    base = base or "section"
+    if base not in used:
+      used.add(base)
+      return base
+    n = 1
+    while f"{base}-{n}" in used:
+      n += 1
+    used.add(f"{base}-{n}")
+    return f"{base}-{n}"
+
+  seen_explicit = set()
+  n_lines = text.count("\n") + (0 if text.endswith("\n") or not text else 1)
+  sections, stack = [], []
+  for (tok, inline), eid in zip(heads, explicit):
+    title = _plain(inline)
+    if eid and eid not in seen_explicit:
+      seen_explicit.add(eid)
+      sid = eid
+    elif eid:
+      sid = unique(eid)  # the first owner keeps it; this one gets a suffix
+    else:
+      sid = unique(slug(title))
+    level = int(tok.tag[1])
+    sec = Section(sid, level, title, tok.map[0] + 1, n_lines)
+    while stack and stack[-1].level >= level:
+      stack.pop().end = sec.line - 1
+    if stack:
+      sec.parent = stack[-1]
+      stack[-1].children.append(sec)
+    stack.append(sec)
+    sections.append(sec)
+    tok.meta["section"] = sec
+  return Doc(text, tokens, sections, warnings)
+
+
+def section_at(doc, line):
+  """The deepest section containing 1-based `line`, or None above the first
+  heading."""
+  best = None
+  for sec in doc.sections:
+    if sec.line <= line <= sec.end:
+      best = sec
+  return best
+
+
+def line_of(doc, section_id):
+  for sec in doc.sections:
+    if sec.id == section_id:
+      return sec.line
+  return None
+
+
+# ------------------------------------------------------------------ render
+
+def render(doc, rewrite=None, task_href=None):
+  """HTML with each section wrapped in nested `<section>` elements.
+
+  `rewrite(href)` maps a local link to its URL, or returns None for a target
+  the reader cannot serve. `task_href(n)` gives the link for task row `n` of
+  a Project.md, or None."""
+  # Render rules set attributes on tokens; work on a copy so a Doc can be
+  # rendered more than once.
+  tokens = copy.deepcopy(doc.tokens)
+  if task_href:
+    tokens = _link_task_rows(doc, tokens, task_href)
+  out, depth_levels = [], []
+  for tok in tokens:
+    sec = tok.meta.get("section") if tok.type == "heading_open" else None
+    if sec:
+      while depth_levels and depth_levels[-1] >= sec.level:
+        depth_levels.pop()
+        out.append(_html("</section>\n"))
+      out.append(_html(
+          f'<section id="{escapeHtml(sec.id)}" data-level="{sec.level}" '
+          f'data-line="{sec.line}" data-end="{sec.end}">\n'))
+      depth_levels.append(sec.level)
+      tok.attrSet("class", "sec-h")
+    out.append(tok)
+  out.extend(_html("</section>\n") for _ in depth_levels)
+  return _MD.renderer.render(out, _MD.options,
+                             {"rewrite": rewrite or (lambda h: h)})
+
+
+def _html(content):
+  tok = Token("html_block", "", 0)
+  tok.content = content
+  return tok
+
+
+def _link_task_rows(doc, tokens, task_href):
+  lines = doc.text.split("\n")
+  out = list(tokens)
+  i = 0
+  while i < len(out):
+    tok = out[i]
+    if tok.type == "list_item_open" and tok.map:
+      m = TASK_RE.match(lines[tok.map[0]].lstrip())
+      href = m and task_href(int(m.group(1)))
+      if href:
+        for j in range(i + 1, len(out)):
+          if out[j].type == "inline":
+            link_open = Token("link_open", "a", 1)
+            link_open.attrSet("href", href)
+            link_open.attrSet("class", "task-link")
+            inline = out[j].copy()
+            inline.children = ([link_open] + list(inline.children or [])
+                               + [Token("link_close", "a", -1)])
+            out[j] = inline
+            break
+          if out[j].type == "list_item_close":
+            break
+    i += 1
+  return out
+
+
+def _math_span(display):
+  def rule(self, tokens, idx, options, env):
+    return (f'<span class="math" data-display="{int(display)}">'
+            f"{escapeHtml(tokens[idx].content)}</span>")
+  return rule
+
+
+def _math_div(self, tokens, idx, options, env):
+  return (f'<div class="math" data-display="1">'
+          f"{escapeHtml(tokens[idx].content)}</div>\n")
+
+
+def _fence(self, tokens, idx, options, env):
+  tok = tokens[idx]
+  if tok.info.strip().split(" ")[0] == "mermaid":
+    return f'<pre class="mermaid">{escapeHtml(tok.content)}</pre>\n'
+  return RendererHTML.fence(self, tokens, idx, options, env)
+
+
+def _link_open(self, tokens, idx, options, env):
+  tok = tokens[idx]
+  href = tok.attrGet("href")
+  if href is not None:
+    new = env["rewrite"](href)
+    if new is None:
+      tok.attrs.pop("href", None)
+      tok.attrSet("class", "unreachable")
+      tok.attrSet("title", f"{href} (not under a served root)")
+    else:
+      tok.attrSet("href", new)
+  return self.renderToken(tokens, idx, options, env)
+
+
+def _image(self, tokens, idx, options, env):
+  tok = tokens[idx]
+  src = env["rewrite"](tok.attrGet("src") or "")
+  tok.attrSet("src", src or "")
+  return RendererHTML.image(self, tokens, idx, options, env)
+
+
+def _list_item_open(self, tokens, idx, options, env):
+  tok = tokens[idx]
+  # Keep the source number: markdown renumbers an ordered list from its
+  # first item, which would show Project.md's sparse task numbers wrong.
+  if tok.info and tok.info.isdigit():
+    tok.attrSet("value", tok.info)
+  return self.renderToken(tokens, idx, options, env)
+
+
+# After the render rules it refers to.
+_MD = make_markdown()

doc_reader/nvim/lua/doc_reader.lua

@@ -0,0 +1,43 @@
+-- doc-reader: <leader>h prints the reader URL of the section under the cursor.
+-- The section is found by `docread url --stdin` from the buffer's text, so
+-- unsaved edits count and the editor and the page share one parser.
+local M = {}
+
+M.cmd = { "docread" }
+
+function M.url()
+  local path = vim.api.nvim_buf_get_name(0)
+  if path == "" then
+    vim.notify("doc-reader: buffer has no file", vim.log.levels.WARN)
+    return
+  end
+  local line = vim.api.nvim_win_get_cursor(0)[1]
+  local text = table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), "\n")
+  local argv = vim.list_extend(vim.deepcopy(M.cmd), { "url", "--stdin", path, tostring(line) })
+  local out = vim.fn.system(argv, text)
+  if vim.v.shell_error ~= 0 then
+    vim.notify("doc-reader: " .. vim.trim(out), vim.log.levels.WARN)
+    return
+  end
+  local chunks = { { vim.trim(out) } }
+  if vim.bo.modified then
+    table.insert(chunks, { "  (unsaved: the page may differ)", "Comment" })
+  end
+  vim.api.nvim_echo(chunks, false, {})
+  return chunks[1][1]
+end
+
+function M.setup(opts)
+  opts = opts or {}
+  M.cmd = opts.cmd or M.cmd
+  local keymap = opts.keymap or "<leader>h"
+  vim.api.nvim_create_autocmd("FileType", {
+    pattern = "markdown",
+    group = vim.api.nvim_create_augroup("doc_reader", { clear = true }),
+    callback = function(ev)
+      vim.keymap.set("n", keymap, M.url, { buffer = ev.buf, desc = "doc-reader: section URL" })
+    end,
+  })
+end
+
+return M