Developer Tools
vdoc
Reads the comments in your source and turns them into reference pages.
Released v1.0.0 · 2026-09-28use "stdlib/doc.ven"Turns the doc comments in your source into reference pages: escapes text for HTML, tidies prose and assembles one entry per function or keyword.
print escape_for_html("<a> & <b>")API reference
doc_entry(kind, name, signature, summary, prose, examples, params = [], returns = "", see_also = [])
Builds one hand-authored DocEntry.
doc_entry("intrinsic", "print", "print value, ...", "Writes a value to standard output.", "print is a reserved statement keyword, not a function.", ["print \"hi\""])humanize_text(text)
Replaces every em dash and double or triple hyphen in text with a comma.
humanize_text("fast -- reliable --- simple")collapse_lines(text)
Joins every line of text back into one line, separated by spaces.
collapse_lines("Advanced version\nof: Python's csv module.")paragraph_is_comparison(paragraph)
Tests whether paragraph is comparison framing against another language.
paragraph_is_comparison("Advanced version of: Python's csv module")strip_comparison_framing(text)
Drops every comparison-framing paragraph out of text, keeping the rest.
strip_comparison_framing("A plain paragraph.\n\nAdvanced version of: Python's csv module.")prepare_prose(text)
Prepares one piece of prose for rendering: strips comparison framing, then humanizes dashes.
prepare_prose("Advanced version of: Python's csv.\n\nReads rows -- fast.")is_word_char(ch)
Tests whether ch is a character highlight_code treats as part of an identifier.
is_word_char("_")is_venutian_keyword(word)
Tests whether word is one of Venutian's own reserved keywords.
is_venutian_keyword("repeat")highlight_code(code)
highlight_code("make add(a, b)\n give a + b")slugify(text)
Turns text into a lowercase, hyphen-separated slug safe for an HTML id.
slugify("Core Builtins: Math")comment_body(trimmed_line)
Strips the :: marker and one separating space off a comment line.
comment_body(":: escape_for_html(text)")is_comment_line(trimmed_line)
Tests whether trimmed_line is a :: documentation comment line.
is_comment_line(":: A comment line.")first_nonempty_line(text)
Gives back the first non-blank line of text, trimmed.
first_nonempty_line("\n\n A one-line summary.\nMore detail follows.")parse_param_line(body)
Splits one @param name: description tag body into a [name, description] pair.
parse_param_line("text: the raw Text to escape")parse_returns_line(body)
Strips an @returns tag's own prefix off body, leaving just the description.
parse_returns_line(": a new Text with every character escaped")parse_see_line(body)
Splits one @see name, name, ... tag body into a list of bare symbol names.
parse_see_line("escape_for_html, slugify")split_prose_and_examples(pending)
Sorts a comment block's lines into prose, example lines, and tag data.
split_prose_and_examples(["Adds two numbers.", "", "@param a: the first addend", "", " add(1, 2)"])body_docstring(lines, next_index)
Gives back a declaration's leading bare Text-literal docstring, if any.
body_docstring(["make add(a, b)", " \"Adds two numbers.\"", " give a + b"], 1)module_overview(source_text)
Gives back a module's leading :: comment run, as prose.
module_overview(":: sample, fixture module for vdoc's own test suite.\n\nmake greet(name)")module_category(source_text)
Gives back a module's topic category from its header comment run.
module_category(":: vdoc, Venutian's own documentation engine.\n::\n:: @category: Documentation & Site Tooling\n\nmake foo()")module_name_from_path(path)
Derives a bare module name from a file path, dropping directories and extension.
module_name_from_path("stdlib/doc.ven")parse_function_line(t, is_tool)
Extracts the bare function name out of a make/tool make declaration line.
parse_function_line("make add(a, b)", no)build_function_entry(lines, i, t, pending, is_tool)
Builds one DocEntry for a scanned make or tool make declaration.
build_function_entry(["make add(a, b)", " give a + b"], 0, "make add(a, b)", ["Adds two numbers."], no)build_shape_entry(t, pending)
Builds one DocEntry for a scanned shape declaration.
build_shape_entry("shape Point", [":: A single point in 2D space."])build_behavior_entry(t, pending)
Builds one DocEntry for a scanned behavior declaration.
build_behavior_entry("behavior Point", [":: Methods for measuring a Point."])parse_module(source_text)
Scans a whole .ven source file into a list of DocEntry values.
parse_module(":: Adds two numbers.\nmake add(a, b)\n give a + b")entries_of_kind(entries, kind)
Filters entries down to just the ones whose kind matches kind.
entries_of_kind([doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])], "make")count_of_kind(entries, kind)
Counts how many of entries have the given kind.
count_of_kind([doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])], "make")badge_ink(kind)
badge_ink("shape")badge_bg(kind)
badge_bg("shape")kind_label(kind)
Gives back the singular, human-readable label for a declaration kind.
kind_label("make")kind_plural(kind)
Gives back the plural, human-readable label for a declaration kind.
kind_plural("shape")render_font_face()
Builds the @font-face rule for the self-hosted Bodoni Moda variable font.
render_font_face()render_head(title)
Builds the page's <head> element, including the inline stylesheet.
render_head("vdoc")render_stat(count, label)
render_stat(42, "Functions")render_hero(title, overview)
Builds the page's hero header: shelf tag, title, and overview paragraph.
render_hero("vdoc", "Venutian's own documentation engine.")render_stats_row(entries)
Builds the hero's row of tally stats and closes the hero header.
render_stats_row([doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])])render_toc(entries)
Builds the sidebar table of contents for a single page's entries.
render_toc([doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])])render_examples(examples)
Builds a card's runnable EXAMPLE block, or nothing when there is no example.
render_examples(["add(1, 2)"])build_symbol_index_local(entries)
Builds a same-page symbol index: every entry's name paired with its own anchor.
build_symbol_index_local([doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])])render_params_html(params)
Builds the card's PARAMETERS block, from @param tags.
render_params_html([["text", "the raw Text to escape"]])render_returns_html(returns_text)
Builds the card's RETURNS block, from an @returns tag.
render_returns_html("a new Text with every HTML-sensitive character replaced by its entity")resolve_see_also_html(names, symbol_index)
Builds the card's SEE ALSO block, resolving each name against a symbol index.
resolve_see_also_html(["escape_for_html"], [["escape_for_html", "#entry-escape_for_html"]])render_card(e, symbol_index = [])
render_card(doc_entry("make", "add", "add(a, b)", "Adds two numbers.", "Adds a and b together.", ["add(1, 2)"]))render_cards(entries)
Builds the <main> element holding every entry's card, for a single-module page.
render_cards([doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])])render_script()
Builds the page's client-side <script>: search, filters, TOC spy, and reveal animation.
render_script()render_theme_toggle_js()
render_theme_toggle_js()render_html(title, overview, entries)
Assembles one complete, single-module HTML page from title, overview, and entries.
render_html("vdoc", "Venutian's own documentation engine.", [doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])])book_section(title, overview, entries, category = "Uncategorized")
Builds one BookSection.
book_section("vdoc", "Venutian's own documentation engine.", [], "Documentation & Site Tooling")all_entries(sections)
Flattens every section's entries into one combined list, in section order.
all_entries([book_section("vdoc", "overview", [doc_entry("make", "add", "add(a, b)", "Adds.", "Adds a and b.", [])])])render_module_section(section)
Builds one module's whole section inside the full reference book: title, overview, and cards.
render_module_section(book_section("vdoc", "Venutian's own documentation engine.", []))render_book_toc(sections)
Builds the full reference book's top-level table of contents, one link per section.
render_book_toc([book_section("vdoc", "Venutian's own documentation engine.", [])])glossary_term(term, definition_html)
Builds one <dt>/<dd> definition-list entry for the glossary.
glossary_term("give", "The word that hands a value back out of a function.")render_glossary_html()
Builds the book's "Start Here" section: a plain-language glossary for a first-time reader.
render_glossary_html()render_book_html(book_title, book_intro, sections)
Assembles one complete, multi-module "study guide" HTML page from every section.
render_book_html("Venutian Study Guide", "A complete guide.", [book_section("vdoc", "overview", [])])build_full_reference(book_title, book_intro, module_paths, extra_sections, output_path)
Builds and writes the complete, multi-module reference book to disk.
build_full_reference("Venutian Study Guide", "A complete guide.", ["stdlib/doc.ven"], [], "site/study-guide.html")generate_docs(source_path, output_path)
Autodocs a real .ven file, writing one finished HTML page to disk.
generate_docs("stdlib/doc.ven", "site/pkg-vdoc.html")generate_docs_from_entries(title, overview, entries, output_path)
Writes a finished HTML page from hand-authored DocEntry values, with no source file to scan.
generate_docs_from_entries("Core Intrinsics", "The words built directly into Venutian.", [doc_entry("intrinsic", "print", "print value, ...", "Writes a value to standard output.", "print is a reserved statement keyword.", ["print \"hi\""])], "site/pkg-intrinsics.html")