2026-01-26 04:12:14 +00:00
{# retoor < retoor @ molodetz . nl > #}
{% extends 'page.html' %}
2026-01-25 18:02:02 +00:00
2026-01-26 04:12:14 +00:00
{% set page_title = "Documentation" %}
{% set breadcrumb = [{"url": "contributing/index.html", "title": "Contributing"}, {"title": "Documentation"}] %}
{% set prev_page = {"url": "contributing/testing.html", "title": "Writing Tests"} %}
{% set next_page = {"url": "api/index.html", "title": "API Reference"} %}
{% block article %}
2026-01-25 18:02:02 +00:00
< h1 > Documentation</ h1 >
< p > The Wren-CLI manual is hand-written HTML in < code > manual/</ code > . There is no generation step. Every page is a standalone HTML file sharing common CSS and JavaScript.</ p >
< h2 > HTML Template</ h2 >
< p > Every page follows this structure:</ p >
< pre >< code > < !DOCTYPE html>
< !-- retoor < retoor@molodetz.nl> -->
< html lang="en">
< head>
< meta charset="UTF-8">
< meta name="viewport" content="width=device-width, initial-scale=1.0">
< title> [Page Title] - Wren-CLI Manual< /title>
< link rel="stylesheet" href="../css/style.css">
< /head>
< body>
< button class="mobile-menu-toggle"> Menu< /button>
< div class="container">
< aside class="sidebar">
< div class="sidebar-header">
< h1>< a href="../index.html"> Wren-CLI< /a>< /h1>
< div class="version"> v0.4.0< /div>
< /div>
< nav class="sidebar-nav">
< !-- Auto-generated by sync_sidebar.py -->
< /nav>
< /aside>
< main class="content">
< nav class="breadcrumb">
< a href="../index.html"> Home< /a>
< span class="separator"> /< /span>
< a href="index.html"> API Reference< /a>
< span class="separator"> /< /span>
< span> [Current Page]< /span>
< /nav>
< article>
< h1> [Page Title]< /h1>
< !-- Content -->
< /article>
< footer class="page-footer">
< a href="[prev].html" class="prev"> [Previous]< /a>
< a href="[next].html" class="next"> [Next]< /a>
< /footer>
< /main>
< /div>
< script src="../js/main.js">< /script>
< /body>
< /html> </ code ></ pre >
< h2 > Sidebar Navigation</ h2 >
< p > The sidebar is automatically synchronized across all pages by < code > util/sync_sidebar.py</ code > . Never edit the sidebar manually.</ p >
< h3 > Adding a New Module to the Sidebar</ h3 >
< ol >
< li > Create the module's HTML page in < code > manual/api/</ code ></ li >
< li > Run < code > make sync-manual</ code ></ li >
</ ol >
< p > The sync script automatically discovers new API pages and adds them to the sidebar in alphabetical order.</ p >
< h3 > Adding a New Section</ h3 >
< p > To add a new top-level section (like "Contributing"), edit < code > util/sync_sidebar.py</ code > and add an entry to the < code > SECTIONS</ code > list:</ p >
< pre >< code > {
"title": "New Section",
"directory": "new-section",
"pages": [
("index.html", "Overview"),
("page1.html", "Page One"),
("page2.html", "Page Two"),
]
},</ code ></ pre >
< h2 > API Page Structure</ h2 >
< p > API documentation pages follow a consistent structure:</ p >
< pre >< code > < h1> modulename< /h1>
< p> Description paragraph.< /p>
< pre>< code> import "modulename" for ClassName< /code>< /pre>
< div class="class-header">< h2> Class: ClassName< /h2>< /div>
< h3> Static Methods< /h3>
< div class="method-signature">
< span class="method-name"> ClassName.methodName< /span> (< span class="param"> arg< /span> )
& rarr; < span class="type"> ReturnType< /span>
< /div>
< p> Method description.< /p>
< h3> Examples< /h3>
< pre>< code> import "modulename" for ClassName
var result = ClassName.methodName("hello")
System.print(result)< /code>< /pre> </ code ></ pre >
< h2 > CSS Classes</ h2 >
< table >
< tr >
< th > Class</ th >
< th > Usage</ th >
</ tr >
< tr >
< td >< code > .method-signature</ code ></ td >
< td > Method signature box</ td >
</ tr >
< tr >
< td >< code > .method-name</ code ></ td >
< td > Method name within signature</ td >
</ tr >
< tr >
< td >< code > .param</ code ></ td >
< td > Parameter name</ td >
</ tr >
< tr >
< td >< code > .type</ code ></ td >
< td > Return type</ td >
</ tr >
< tr >
< td >< code > .class-header</ code ></ td >
< td > Class section header</ td >
</ tr >
< tr >
< td >< code > .param-list</ code ></ td >
< td > Parameter description list</ td >
</ tr >
< tr >
< td >< code > .toc</ code ></ td >
< td > Table of contents box</ td >
</ tr >
< tr >
< td >< code > .admonition</ code ></ td >
< td > Note/warning/tip box</ td >
</ tr >
< tr >
< td >< code > .example-output</ code ></ td >
< td > Expected output display</ td >
</ tr >
</ table >
< h2 > Method Signature Format</ h2 >
< p > Static method:</ p >
< pre >< code > < div class="method-signature">
< span class="method-name"> ClassName.methodName< /span> (< span class="param"> arg1< /span> , < span class="param"> arg2< /span> )
& rarr; < span class="type"> String< /span>
< /div> </ code ></ pre >
< p > Instance method:</ p >
< pre >< code > < div class="method-signature">
< span class="method-name"> instance.methodName< /span> (< span class="param"> arg< /span> )
& rarr; < span class="type"> Bool< /span>
< /div> </ code ></ pre >
< p > Property (getter):</ p >
< pre >< code > < div class="method-signature">
< span class="method-name"> instance.propertyName< /span>
& rarr; < span class="type"> Num< /span>
< /div> </ code ></ pre >
< h2 > Admonition Blocks</ h2 >
< p > Use admonitions for notes, warnings, and tips:</ p >
< h3 > Note</ h3 >
< pre >< code > < div class="admonition note">
< div class="admonition-title"> Note< /div>
< p> Additional information.< /p>
< /div> </ code ></ pre >
< div class = "admonition note" >
< div class = "admonition-title" > Note</ div >
< p > Additional information.</ p >
</ div >
< h3 > Warning</ h3 >
< pre >< code > < div class="admonition warning">
< div class="admonition-title"> Warning< /div>
< p> Important caution.< /p>
< /div> </ code ></ pre >
< div class = "admonition warning" >
< div class = "admonition-title" > Warning</ div >
< p > Important caution.</ p >
</ div >
< h3 > Tip</ h3 >
< pre >< code > < div class="admonition tip">
< div class="admonition-title"> Tip< /div>
< p> Helpful suggestion.< /p>
< /div> </ code ></ pre >
< h2 > Parameter Lists</ h2 >
< p > For methods with complex parameters:</ p >
< pre >< code > < div class="param-list">
< div class="param-item">
< span class="param-name"> path< /span>
< span class="param-type"> String< /span>
< p> The file path to read.< /p>
< /div>
< div class="param-item">
< span class="param-name"> encoding< /span>
< span class="param-type"> String< /span>
< p> The character encoding (default: "utf-8").< /p>
< /div>
< /div> </ code ></ pre >
< h2 > Tables</ h2 >
< p > Use tables for options, type mappings, or comparisons:</ p >
< pre >< code > < table>
< tr>
< th> Option< /th>
< th> Description< /th>
< /tr>
< tr>
< td>< code> "r"< /code>< /td>
< td> Read mode< /td>
< /tr>
< tr>
< td>< code> "w"< /code>< /td>
< td> Write mode< /td>
< /tr>
< /table> </ code ></ pre >
< h2 > Footer Navigation</ h2 >
< p > Every page has previous/next navigation:</ p >
< pre >< code > < footer class="page-footer">
< a href="previous.html" class="prev"> Previous Page< /a>
< a href="next.html" class="next"> Next Page< /a>
< /footer> </ code ></ pre >
< p > Update the footer on adjacent pages when adding new pages.</ p >
< h2 > Breadcrumb Navigation</ h2 >
< p > Shows the page hierarchy:</ p >
< pre >< code > < nav class="breadcrumb">
< a href="../index.html"> Home< /a>
< span class="separator"> /< /span>
< a href="index.html"> API Reference< /a>
< span class="separator"> /< /span>
< span> io< /span>
< /nav> </ code ></ pre >
< h2 > Syncing the Sidebar</ h2 >
< pre >< code > make sync-manual</ code ></ pre >
< p > This runs < code > util/sync_sidebar.py</ code > which:</ p >
< ol >
< li > Discovers all API module pages</ li >
< li > Builds the complete sidebar HTML</ li >
< li > Updates the < code > < nav class="sidebar-nav"> </ code > in every HTML file</ li >
< li > Sets the < code > active</ code > class on the current page's link</ li >
</ ol >
< p > The script is idempotent - running it twice produces the same result.</ p >
< h2 > Adding a New API Page</ h2 >
< ol >
< li > Create < code > manual/api/< name> .html</ code ></ li >
< li > Use the template structure above</ li >
< li > Run < code > make sync-manual</ code ></ li >
< li > Update footer prev/next on adjacent pages</ li >
< li > Add entry to < code > manual/api/index.html</ code ></ li >
</ ol >
< h2 > Example: Minimal API Page</ h2 >
< pre >< code > < !DOCTYPE html>
< !-- retoor < retoor@molodetz.nl> -->
< html lang="en">
< head>
< meta charset="UTF-8">
< meta name="viewport" content="width=device-width, initial-scale=1.0">
< title> mymodule - Wren-CLI Manual< /title>
< link rel="stylesheet" href="../css/style.css">
< /head>
< body>
< button class="mobile-menu-toggle"> Menu< /button>
< div class="container">
< aside class="sidebar">
< div class="sidebar-header">
< h1>< a href="../index.html"> Wren-CLI< /a>< /h1>
< div class="version"> v0.4.0< /div>
< /div>
< nav class="sidebar-nav">
< /nav>
< /aside>
< main class="content">
< nav class="breadcrumb">
< a href="../index.html"> Home< /a>
< span class="separator"> /< /span>
< a href="index.html"> API Reference< /a>
< span class="separator"> /< /span>
< span> mymodule< /span>
< /nav>
< article>
< h1> mymodule< /h1>
< p> The < code> mymodule< /code> module provides...< /p>
< pre>< code> import "mymodule" for MyClass< /code>< /pre>
< h2> MyClass< /h2>
< h3> Static Methods< /h3>
< div class="method-signature">
< span class="method-name"> MyClass.process< /span> (< span class="param"> input< /span> )
& rarr; < span class="type"> String< /span>
< /div>
< p> Processes the input and returns a result.< /p>
< h3> Examples< /h3>
< pre>< code> import "mymodule" for MyClass
var result = MyClass.process("hello")
System.print(result)< /code>< /pre>
< /article>
< footer class="page-footer">
< a href="math.html" class="prev"> math< /a>
< a href="net.html" class="next"> net< /a>
< /footer>
< /main>
< /div>
< script src="../js/main.js">< /script>
< /body>
< /html> </ code ></ pre >
< h2 > Checklist for New Documentation</ h2 >
< ul >
< li > Author comment on line 2</ li >
< li > Correct title in < code > < title> </ code > and < code > < h1> </ code ></ li >
< li > Proper breadcrumb navigation</ li >
< li > Import statement example</ li >
< li > All methods documented with signatures</ li >
< li > Working code examples</ li >
< li > Footer with prev/next links</ li >
< li > Ran < code > make sync-manual</ code ></ li >
< li > Updated adjacent page footers</ li >
< li > Added to index page if applicable</ li >
</ ul >
2026-01-26 04:12:14 +00:00
{% endblock %}
