`doc`

Documentation generator - extract doc comments and function signatures from ilusm source text, generate HTML or Markdown documentation pages, build a multi-module index page, build a flat search index, serve documentation over HTTP, and produce an OpenAPI 3.0 specification.

Load with: use doc

What this module does

doc is ilusm's built-in documentation toolchain. Point it at a .ilu source file and it parses the text line by line, collecting # --- doc comments before function definitions and extracting function names, signatures, and parameters. The result is a structured docs object you can render as self-contained HTML or Markdown.

For multi-module projects, docin generates a linked index page and docse builds a flat list of every function across all modules - useful for search or autocomplete. docsr starts a local HTTP server to browse the docs in a browser. docop converts extracted function docs into an OpenAPI 3.0 spec.

Quick example

use doc

# Parse a source file
src = fs.rd("src/math.ilu")
docs = docpa(src)

# docs.functions is a list of {name, signature, params, doc, line, examples}

# Render as HTML
html = docht(docs)
fs.wr("docs/math.html", html)

# Render as Markdown
md = docma(docs)
fs.wr("docs/math.md", md)

# Generate docs for multiple modules at once
docin(["src/math.ilu", "src/txt.ilu"], "docs/index.html")

# Build a search index
idx = docse(["src/math.ilu", "src/txt.ilu"])
# [{name, module, signature, doc, line}, ...]

# Serve locally
docsr(8080, "docs/")

Functions

Parsing

docpa(source)

Parses an ilusm source string. Returns a docs object:

module - {name, doc} extracted from the first use statement
functions - list of {name, signature, params, doc, line, examples}
types and constants - reserved lists

Doc comments are lines starting with # --- immediately preceding a definition. Code examples inside doc comments use triple-backtick fences.

Generating output

docge(source_path, output_format)

Reads a source file, parses it, and returns output in the requested format: "html", "markdown", or "json". Defaults to Markdown for unknown formats.

docht(docs)

Renders the docs object as a self-contained HTML page with inline styles - a title heading, module doc, and a styled card for each function showing its name, signature (with parameter spans), doc text, and any code examples.

docma(docs)

Renders the docs object as a Markdown string with an H1 module title, H2 "Functions" section, and H3 entries for each function with its signature and examples.

Multi-module index

docin(paths, output_path)

Parses each source file in paths, generates a linked HTML index page listing each module with its doc and function count, and writes it to output_path. Returns the output path.

docse(paths)

Parses each source file and returns a flat list of all function records across all modules - useful for full-text search or IDE autocomplete.

HTTP server

docsr(port, doc_dir)

Starts an HTTP server on 127.0.0.1:{port} serving files from doc_dir. Serves index.html at /, HTML files with text/html, CSS with text/css, JS with application/javascript. Returns 404 for missing files.

OpenAPI

docop(docs)

Converts a parsed docs object into an OpenAPI 3.0 spec object. Each function becomes a GET path at /{fn.name} with its parameters as query parameters. Returns {openapi, info, paths}.

Notes

Only # --- comments immediately before a definition are treated as doc comments. Regular # comments are ignored.
Requires trl, txt, jsn, and tpl. The docsr function also requires srv and fs.