Lunaphied
7a1054fa5f
For a long time `nix repl` has supported displaying documentation set on
builtins, however, it has long been convention to use Markdown comments
on Nix functions themselves for documentation. This exposes that
information to `nix repl` users in a nice and formatted way.
NixOS/rfcs#145 doc-comments are primarily what this feature is intended
to consume, however, support for lambda documentation in the repl is
experimental. We do our best effort to support the RFC here.
These changes are based on [the nix-doc library](https://github.com/lf-/nix-doc) and
are licensed under the terms described in the relevant source files.
Change-Id: Ic6fe947d39a22540705d890737e336c4720b0a22
67 lines
2.2 KiB
Python
67 lines
2.2 KiB
Python
import frontmatter
|
|
import sys
|
|
import pathlib
|
|
import textwrap
|
|
|
|
GH_BASE = "https://github.com/NixOS/nix"
|
|
FORGEJO_BASE = "https://git.lix.systems/lix-project/lix"
|
|
GERRIT_BASE = "https://gerrit.lix.systems/c/lix/+"
|
|
|
|
SIGNIFICANCECES = {
|
|
None: 0,
|
|
'significant': 10,
|
|
}
|
|
|
|
def format_link(ident: str, gh_part: str, fj_part: str) -> str:
|
|
# FIXME: deprecate github as default
|
|
if ident.isdigit():
|
|
num, link, base = int(ident), f"#{ident}", f"{GH_BASE}/{gh_part}"
|
|
elif ident.startswith("gh#"):
|
|
num, link, base = int(ident[3:]), ident, f"{GH_BASE}/{gh_part}"
|
|
elif ident.startswith("fj#"):
|
|
num, link, base = int(ident[3:]), ident, f"{FORGEJO_BASE}/{fj_part}"
|
|
else:
|
|
raise Exception("unrecognized reference format", ident)
|
|
return f"[{link}]({base}/{num})"
|
|
|
|
def format_issue(issue: str) -> str:
|
|
return format_link(issue, "issues", "issues")
|
|
def format_pr(pr: str) -> str:
|
|
return format_link(pr, "pull", "pulls")
|
|
def format_cl(cl: str) -> str:
|
|
clid = int(cl)
|
|
return f"[cl/{clid}]({GERRIT_BASE}/{clid})"
|
|
|
|
paths = pathlib.Path(sys.argv[1]).glob('*.md')
|
|
entries = []
|
|
for p in paths:
|
|
try:
|
|
e = frontmatter.load(p)
|
|
if 'synopsis' not in e.metadata:
|
|
raise Exception('missing synopsis')
|
|
unknownKeys = set(e.metadata.keys()) - set(('synopsis', 'cls', 'issues', 'prs', 'significance'))
|
|
if unknownKeys:
|
|
raise Exception('unknown keys', unknownKeys)
|
|
entries.append((p, e))
|
|
except Exception as e:
|
|
e.add_note(f"in {p}")
|
|
raise
|
|
|
|
for p, entry in sorted(entries, key=lambda e: (-SIGNIFICANCECES[e[1].metadata.get('significance')], e[0])):
|
|
try:
|
|
header = entry.metadata['synopsis']
|
|
links = []
|
|
links += map(format_issue, str(entry.metadata.get('issues', "")).split())
|
|
links += map(format_pr, str(entry.metadata.get('prs', "")).split())
|
|
links += map(format_cl, str(entry.metadata.get('cls', "")).split())
|
|
if links != []:
|
|
header += " " + " ".join(links)
|
|
if header:
|
|
print(f"- {header}")
|
|
print()
|
|
print(textwrap.indent(entry.content, ' '))
|
|
print()
|
|
except Exception as e:
|
|
e.add_note(f"in {p}")
|
|
raise
|