The one ordered document corpus behind apropos(pattern) and doc(name).
Static resources and live sources contribute the same closed record shape. Invalid static records fail at load; invalid dynamic records are logged and dropped.
entries is the whole corpus in source order, deduplicated by EXACT name; pages
is the documentation subset the docs site renders. A page can give an example
twice, as a Python and an HTTP variant. entries gives the agent only the
Python variant, without the markup. pages keeps both for the site.
apropos applies one regular expression to record names, reading a hyphenated
name also as words, and to the outline of pages and skills: title, opening,
headings, When to use problems.
It preserves corpus order. There is no ranking, tokenization, search index or
classpath discovery. doc retrieves the same record by name and prints its
whole text.
The one ordered document corpus behind `apropos(pattern)` and `doc(name)`. Static resources and live sources contribute the same closed record shape. Invalid static records fail at load; invalid dynamic records are logged and dropped. `entries` is the whole corpus in source order, deduplicated by EXACT name; `pages` is the documentation subset the docs site renders. A page can give an example twice, as a Python and an HTTP variant. `entries` gives the agent only the Python variant, without the markup. `pages` keeps both for the site. `apropos` applies one regular expression to record names, reading a hyphenated name also as words, and to the outline of pages and skills: title, opening, headings, `When to use` problems. It preserves corpus order. There is no ranking, tokenization, search index or classpath discovery. `doc` retrieves the same record by name and prints its whole text.
The variant of a paired page that apropos and doc give the agent. A page
can give one example twice, in a <div data-variant="python"> block and then
a <div data-variant="http"> block. The site shows both, with a switch. The
agent writes Python, so it gets the Python block without the markup.
The variant of a paired page that `apropos` and `doc` give the agent. A page can give one example twice, in a `<div data-variant="python">` block and then a `<div data-variant="http">` block. The site shows both, with a switch. The agent writes Python, so it gets the Python block without the markup.
(body-text text)The opening of text capped at body-max-len: the body an apropos row
shows. The first paragraph is enough; the complete document remains one
doc(name) away.
The opening of `text` capped at `body-max-len`: the `body` an `apropos` row shows. The first paragraph is enough; the complete document remains one `doc(name)` away.
What doc() prints: a hand-ordered short list of the verbs a session starts
from, not a corpus dump. Everything else remains addressable through
apropos(pattern) and doc(name).
What `doc()` prints: a hand-ordered short list of the verbs a session starts from, not a corpus dump. Everything else remains addressable through `apropos(pattern)` and `doc(name)`.
(entries)The corpus that apropos and doc read, in source order and deduplicated by
name (first wins). A documentation page arrives in its agent-variant only,
so every agent-facing read, search included, shares ONE filter.
The corpus that `apropos` and `doc` read, in source order and deduplicated by name (first wins). A documentation page arrives in its `agent-variant` only, so every agent-facing read, search included, shares ONE filter.
(entry-text entry)(entry-text {:keys [name text call params result]} note)What doc(target) answers for one entry: the handle, the expression that
uses it when there is one, the keys that expression's options dict must carry,
the raw result it returns, then the WHOLE document. note is the caller's
one-word remark about the handle (env-python marks a live callable).
What `doc(target)` answers for one entry: the handle, the expression that uses it when there is one, the keys that expression's options dict must carry, the raw result it returns, then the WHOLE document. `note` is the caller's one-word remark about the handle (`env-python` marks a live callable).
(forget-records!)Drop the cached read so the next ask reaches for the resources again — what
/reload calls. In a binary the resources are frozen and this costs one re-read;
in a development JVM it is what makes an edited page visible without a restart.
Drop the cached read so the next ask reaches for the resources again — what `/reload` calls. In a binary the resources are frozen and this costs one re-read; in a development JVM it is what makes an edited page visible without a restart.
(gist text)(gist text max-len)The FIRST LINE of text, as a one-liner: leading markdown heading marks are
dropped (a page's first line is its # Title) and the result is capped at
gist-max-len — or at max-len, which the curated index tightens so twenty
rows stay scannable. This is the only place a gist exists — never a stored
field.
The FIRST LINE of `text`, as a one-liner: leading markdown heading marks are dropped (a page's first line is its `# Title`) and the result is capped at `gist-max-len` — or at `max-len`, which the curated index tightens so twenty rows stay scannable. This is the only place a gist exists — never a stored field.
(index-text es)What bare doc() answers: curated verbs that are actually present, one
name — first line per row. Everything else is one apropos(pattern) away.
What bare `doc()` answers: curated verbs that are actually present, one `name — first line` per row. Everything else is one `apropos(pattern)` away.
The closed vocabulary of :kind — what a document IS, which is how a reader
decides what to DO with it, and what doc RETURNS for it: function a
callable's docstring, class a class's, module an importable module's,
tool a Vis verb's contract, doc a whole documentation page, skill a whole
SKILL.md, local a callable this session defined that carries no contract at
all — reachable by name through doc, never returned by apropos.
The closed vocabulary of `:kind` — what a document IS, which is how a reader decides what to DO with it, and what `doc` RETURNS for it: `function` a callable's docstring, `class` a class's, `module` an importable module's, `tool` a Vis verb's contract, `doc` a whole documentation page, `skill` a whole `SKILL.md`, `local` a callable this session defined that carries no contract at all — reachable by name through `doc`, never returned by `apropos`.
(miss-text es target)What doc(target) answers when nothing carries that handle: the handles in
es whose name or outline contains the target literally, names first, so a
near miss costs one more doc call instead of a search.
What `doc(target)` answers when nothing carries that handle: the handles in `es` whose name or outline contains the target literally, names first, so a near miss costs one more `doc` call instead of a search.
(normalize-name target)Coerce a caller's target to a comparable handle: unwrap the map/kwargs shape,
trim, drop a trailing .md (pages cross-link by filename), lower-case. This
is why doc("Index.md") and doc("index") are the same ask.
Coerce a caller's target to a comparable handle: unwrap the map/kwargs shape,
trim, drop a trailing `.md` (pages cross-link by filename), lower-case. This
is why `doc("Index.md")` and `doc("index")` are the same ask.(outline {:keys [kind text]})The phrases a documentation page or skill is found by besides its name: its
opening paragraph, every heading outside fenced code — the title included —
and the bold problem statements its When to use section lists. Other kinds
have no outline.
The phrases a documentation page or skill is found by besides its name: its opening paragraph, every heading outside fenced code — the title included — and the bold problem statements its `When to use` section lists. Other kinds have no outline.
(pages)Every documentation PAGE, in manifest order and whole, with every variant — the
doc kind of the corpus. The docs site renders from THIS: one read, one
validation, one order, and no second reader of the same resources.
Every documentation PAGE, in manifest order and whole, with every variant — the `doc` kind of the corpus. The docs site renders from THIS: one read, one validation, one order, and no second reader of the same resources.
(register-source! id entries-fn)Register a 0-arity entries-fn under id.
Sources are read directly whenever apropos or doc asks for the corpus.
Re-registering an id replaces it IN PLACE, so a reloaded namespace never
duplicates its own entries.
Register a 0-arity `entries-fn` under `id`. Sources are read directly whenever `apropos` or `doc` asks for the corpus. Re-registering an `id` replaces it IN PLACE, so a reloaded namespace never duplicates its own entries.
(search es pattern)Return entries pattern finds, preserving corpus order: a match in one of the
name-forms or in one phrase of a page's or skill's outline. A string pattern
ignores case; a compiled Pattern keeps its own flags. A blank string lists
every entry. Invalid regular expressions are errors.
Return entries `pattern` finds, preserving corpus order: a match in one of the `name-forms` or in one phrase of a page's or skill's `outline`. A string pattern ignores case; a compiled `Pattern` keeps its own flags. A blank string lists every entry. Invalid regular expressions are errors.
(variant-lines md)PURE: each line of md as {:text line :variant name :tag kind :fenced? bool}.
:variant names the block that holds the line, and is nil outside every block.
:tag is :open or :close on the markup lines of a block. A line in fenced
code is never a tag, so a page can show the markup in an example.
PURE: each line of `md` as `{:text line :variant name :tag kind :fenced? bool}`.
`:variant` names the block that holds the line, and is nil outside every block.
`:tag` is `:open` or `:close` on the markup lines of a block. A line in fenced
code is never a tag, so a page can show the markup in an example.(variant-text md variant)PURE: md as a reader of variant gets it. Lines outside every block stay.
A variant block keeps its lines without its tags. Other blocks go. A blank
line next to a removed line merges with its neighbour, so no gap stays. Text
without a block comes back unchanged.
PURE: `md` as a reader of `variant` gets it. Lines outside every block stay. A `variant` block keeps its lines without its tags. Other blocks go. A blank line next to a removed line merges with its neighbour, so no gap stays. Text without a block comes back unchanged.
(variants md)PURE: the names of the variant blocks in md, in page order, each one once.
PURE: the names of the variant blocks in `md`, in page order, each one once.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |