nvim-doc-reader 0.1.0__tar.gz

nvim_doc_reader-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: nvim-doc-reader
+Version: 0.1.0
+Summary: Keyboard-driven HTML reader for Markdown docs, with jumps into running Neovim
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: markdown-it-py<3,>=2.1
+Requires-Dist: mdit-py-plugins<0.4,>=0.3.4
+Requires-Dist: aiohttp>=3.8
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+
+# doc-reader
+
+A keyboard-driven HTML reader for Markdown documents, with jumps into the
+Neovim instances you are editing them in. Markdown stays the only source: the
+server renders it on every request, and the page follows edits live.
+
+- Nested, foldable sections (`zM` to an outline, `l` to drill in), Vim keys.
+- Math (KaTeX), Mermaid diagrams, SVG/PNG figures, tables.
+- `n` moves every running Neovim that has the file to the section you are
+  reading; `nvimd` opens it when none has.
+- `q` copies a question prompt for a coding agent; `y` copies a link.
+- `<leader>h` in Neovim prints the reader URL of the section under the cursor.
+
+## Install
+
+```bash
+pip install nvim-doc-reader
+docread serve
+```
+
+Requires Python 3.9+ and, for the editor features, Neovim 0.9+.
+
+## Configure
+
+`$XDG_CONFIG_HOME/doc-reader/config.toml` (or `$DOCREADER_CONFIG`):
+
+```toml
+# Optional, with their defaults.
+bind = "0.0.0.0"
+port = 8765
+public_url = "http://desknikos:8765"   # what `docread url` prints; default http://localhost:<port>
+nvim = "nvim"
+# nvim_socket_glob: default is where Neovim puts its own socket
+# ($XDG_RUNTIME_DIR/nvim.*.0, else $TMPDIR/nvim.<user>/*/nvim.*.0)
+state_file = "$XDG_STATE_HOME/doc-reader/last"
+poll_interval_s = 0.5
+
+# Which directories are served, by name. The name is part of the URL:
+# /efs/nikos/notes/a.md  ->  /v/nikos/notes/a.md
+# Default: the home directory, as "home".
+[roots]
+nikos = "/efs/nikos"
+```
+
+Every scalar key can be overridden with `DOCREADER_<KEY>`, and the roots with
+`DOCREADER_ROOTS=name=/dir:name=/dir`. Nested roots are fine: a file belongs to
+the most specific one, and any other URL for it redirects there.
+
+Only files under a root are served. Raw files are served with
+`Content-Security-Policy: sandbox`, and raw HTML in Markdown is shown as text.
+There is no authentication: run it on a trusted network.
+
+## Keys
+
+| key | action |
+|---|---|
+| `j` / `k` | next / previous heading |
+| `h` / `l` | collapse or go to parent / expand or go to first child |
+| `za` `zo` `zc` `zO` `zC` | toggle / open / close / open all inside / close all inside |
+| `zM` / `zR` | close all / open all |
+| `gg` / `G`, `Ctrl-d` / `Ctrl-u` | top / bottom, half page |
+| `Tab`, `Enter` | focus and follow links |
+| `n` | open in Neovim |
+| `q` | copy a question prompt |
+| `y` | copy the section's link |
+| `o` | show / hide the outline |
+| `?` | help |
+
+## Neovim
+
+`n` needs nothing in the editor: every Neovim listens on its own socket, and
+the server finds them by `nvim_socket_glob`. Windows showing the file move to
+the section; a buffer that is loaded but hidden moves when you next switch to
+it. `nvimd` with no arguments opens the last target; with arguments it is
+plain `nvim`.
+
+For `<leader>h`:
+
+```lua
+vim.opt.rtp:append(vim.fn.trim(vim.fn.system({ "docread", "nvim-path" })))
+require("doc_reader").setup({ cmd = { "docread" }, keymap = "<leader>h" })
+```
+
+## Section IDs
+
+A heading's ID is its explicit `{#id}` if it has one, otherwise GitHub's slug
+of its text, with `-1`, `-2` for repeats. Give a section an explicit ID when
+links to it must survive a rename.
+
+## Agents
+
+Documents written by coding agents read best when they follow a few rules:
+stable `{#id}`s, short overviews with depth in nested subsections, figures
+kept with their source, no fabricated data, and questions answered without
+editing. The rules ship as a Claude Code skill:
+
+```bash
+docread install-skill                 # -> ~/.claude/skills/doc-authoring/
+docread install-skill --dir .claude/skills   # or per project
+```
+
+Then tell agents to use it, in your global `~/.claude/CLAUDE.md` (or a
+project's `CLAUDE.md`):
+
+```markdown
+## Writing Documents
+
+Markdown documents you write for the user (research notes, reports, plans,
+explainers) follow the `doc-authoring` skill — load it before creating or
+editing one.
+```
+
+Other agents: if they read `SKILL.md` skills, point `--dir` at their skills
+directory; otherwise paste the skill's body into `AGENTS.md` / `GEMINI.md`.

nvim_doc_reader-0.1.0/README.md

@@ -0,0 +1,114 @@
+# doc-reader
+
+A keyboard-driven HTML reader for Markdown documents, with jumps into the
+Neovim instances you are editing them in. Markdown stays the only source: the
+server renders it on every request, and the page follows edits live.
+
+- Nested, foldable sections (`zM` to an outline, `l` to drill in), Vim keys.
+- Math (KaTeX), Mermaid diagrams, SVG/PNG figures, tables.
+- `n` moves every running Neovim that has the file to the section you are
+  reading; `nvimd` opens it when none has.
+- `q` copies a question prompt for a coding agent; `y` copies a link.
+- `<leader>h` in Neovim prints the reader URL of the section under the cursor.
+
+## Install
+
+```bash
+pip install nvim-doc-reader
+docread serve
+```
+
+Requires Python 3.9+ and, for the editor features, Neovim 0.9+.
+
+## Configure
+
+`$XDG_CONFIG_HOME/doc-reader/config.toml` (or `$DOCREADER_CONFIG`):
+
+```toml
+# Optional, with their defaults.
+bind = "0.0.0.0"
+port = 8765
+public_url = "http://desknikos:8765"   # what `docread url` prints; default http://localhost:<port>
+nvim = "nvim"
+# nvim_socket_glob: default is where Neovim puts its own socket
+# ($XDG_RUNTIME_DIR/nvim.*.0, else $TMPDIR/nvim.<user>/*/nvim.*.0)
+state_file = "$XDG_STATE_HOME/doc-reader/last"
+poll_interval_s = 0.5
+
+# Which directories are served, by name. The name is part of the URL:
+# /efs/nikos/notes/a.md  ->  /v/nikos/notes/a.md
+# Default: the home directory, as "home".
+[roots]
+nikos = "/efs/nikos"
+```
+
+Every scalar key can be overridden with `DOCREADER_<KEY>`, and the roots with
+`DOCREADER_ROOTS=name=/dir:name=/dir`. Nested roots are fine: a file belongs to
+the most specific one, and any other URL for it redirects there.
+
+Only files under a root are served. Raw files are served with
+`Content-Security-Policy: sandbox`, and raw HTML in Markdown is shown as text.
+There is no authentication: run it on a trusted network.
+
+## Keys
+
+| key | action |
+|---|---|
+| `j` / `k` | next / previous heading |
+| `h` / `l` | collapse or go to parent / expand or go to first child |
+| `za` `zo` `zc` `zO` `zC` | toggle / open / close / open all inside / close all inside |
+| `zM` / `zR` | close all / open all |
+| `gg` / `G`, `Ctrl-d` / `Ctrl-u` | top / bottom, half page |
+| `Tab`, `Enter` | focus and follow links |
+| `n` | open in Neovim |
+| `q` | copy a question prompt |
+| `y` | copy the section's link |
+| `o` | show / hide the outline |
+| `?` | help |
+
+## Neovim
+
+`n` needs nothing in the editor: every Neovim listens on its own socket, and
+the server finds them by `nvim_socket_glob`. Windows showing the file move to
+the section; a buffer that is loaded but hidden moves when you next switch to
+it. `nvimd` with no arguments opens the last target; with arguments it is
+plain `nvim`.
+
+For `<leader>h`:
+
+```lua
+vim.opt.rtp:append(vim.fn.trim(vim.fn.system({ "docread", "nvim-path" })))
+require("doc_reader").setup({ cmd = { "docread" }, keymap = "<leader>h" })
+```
+
+## Section IDs
+
+A heading's ID is its explicit `{#id}` if it has one, otherwise GitHub's slug
+of its text, with `-1`, `-2` for repeats. Give a section an explicit ID when
+links to it must survive a rename.
+
+## Agents
+
+Documents written by coding agents read best when they follow a few rules:
+stable `{#id}`s, short overviews with depth in nested subsections, figures
+kept with their source, no fabricated data, and questions answered without
+editing. The rules ship as a Claude Code skill:
+
+```bash
+docread install-skill                 # -> ~/.claude/skills/doc-authoring/
+docread install-skill --dir .claude/skills   # or per project
+```
+
+Then tell agents to use it, in your global `~/.claude/CLAUDE.md` (or a
+project's `CLAUDE.md`):
+
+```markdown
+## Writing Documents
+
+Markdown documents you write for the user (research notes, reports, plans,
+explainers) follow the `doc-authoring` skill — load it before creating or
+editing one.
+```
+
+Other agents: if they read `SKILL.md` skills, point `--dir` at their skills
+directory; otherwise paste the skill's body into `AGENTS.md` / `GEMINI.md`.

nvim_doc_reader-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nvim-doc-reader"
+version = "0.1.0"
+description = "Keyboard-driven HTML reader for Markdown docs, with jumps into running Neovim"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "markdown-it-py>=2.1,<3",
+    # 0.3.x is the line that supports markdown-it-py 2.x. Heading {#id} is our
+    # own rule, not the attrs plugin, which does not handle it in 0.3.
+    "mdit-py-plugins>=0.3.4,<0.4",
+    "aiohttp>=3.8",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.scripts]
+docread = "doc_reader.cli:main"
+nvimd = "doc_reader.cli:nvimd_main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+doc_reader = ["static/*", "nvim/lua/*.lua", "skills/*/*.md"]

nvim_doc_reader-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nvim_doc_reader-0.1.0/src/doc_reader/__init__.py

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

nvim_doc_reader-0.1.0/src/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())

nvim_doc_reader-0.1.0/src/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