build_DEMOS collects every %!demo block of fcnname and returns html, a char string with the generated HTML for all of them. fcnname is a char string with the name of a function or, for a class member, a "class/method" path. Each demo is wrapped in the demos_template.html card, titled Example: N and given the HTML anchor fcnname-exampleN (with every non-alphanumeric character of fcnname, such as the . of a "Class.method" name, mapped to _ so the id is safe in a CSS selector). A docstring can therefore link to one of its own demos with the short form @url{#exampleN}: the HTML converter expands the bare #exampleN fragment to this fully-qualified anchor, which keeps the reference readable in the command-line help while staying unique on a page that carries several members’ demos.

The optional collapsed is a logical scalar. When true, each example card renders collapsed by default (used for lumped classdef members to keep the page short); a viewer expands it with the card header, and a #exampleN link opens it automatically. When omitted or false, the card renders expanded. When fcnname has no demos, html is returned empty.

Optional Name/Value pairs

Notebook layout

Each demo is rendered as an interleaved notebook instead of a single code block trailed by its aggregated output. The demo is split into cells and laid out as a vertical stack of boxes:

• Comment lines become prose (see the Markdown subset below).
• Code statements become input boxes. Consecutive statements that print nothing are merged into a single box, so muted setup code reads as one block.
• Output produced by a statement is shown in an output box directly beneath it, rather than at the end of the demo. A statement prints when it is left unterminated by a semicolon or when it calls disp, printf, and the like.
• Figures are saved under the assets/ folder of the working directory, shown right after the code that drew them. They are named after their owner as its HTML page is, so the figures of prob.NormalDistribution.pdf are prob.NormalDistribution.pdf-N beside prob.NormalDistribution.pdf.html. The figure number is separated with a -, since _ already stands for the file separator of an old-style "@class/method" name and a function name may itself contain one.

Markdown in comments

Comment text uses a small subset of Markdown, not texinfo, so that the same demo stays readable in the terminal when it is run with the demo command. The supported constructs are:

• inline code `code` rendered as <code>;
• bold **text** and italic *text* emphasis;
• links [text](url);
• paragraphs, separated by a blank comment line;
• unordered lists, whose items start with a - or * marker, and ordered lists, whose items start with a 1. marker.

All comment text is HTML-escaped before the markup is applied. The following are deliberately not supported: any texinfo markup; underscore emphasis _text_, which would mangle identifier names such as a_b_c; and # headings, which would clash with the Octave comment marker.

See also: find_DEMOS, function_texi2html, classdef_texi2html

Source Code: build_DEMOS