1Documenting OpenSCAD Code
2-------------------------------------------------
3
4Documentation comment blocks are all based around a single simple syntax:
5
6 // Block Name(Metadata): TitleText
7 // Body line 1
8 // Body line 2
9 // Body line 3
10
11- The Block Name is one or two words, both starting with a capital letter.
12- The Metadata is in parentheses. It is optional, and can contain fairly arbitrary text, as long as it doesn't include newlines or parentheses. If the Metadata part is not given, the parentheses are optional.
13- A colon `:` will always follow after the Block Name and optional Metadata.
14- The TitleText will be preceded by a space ` `, and can contain arbitrary text, as long as it contains no newlines. The TitleText part is also optional for some header blocks.
15- The body will contain zero or more lines of text indented by three spaces after the comment markers. Each line can contain arbitrary text.
16
17So, for example, a Figure block to show a 640x480 animated GIF of a spinning shape may look like:
18
19 // Figure(Spin,Size=640x480,VPD=444): A Cube and Cylinder.
20 // cube(80, center=true);
21 // cylinder(h=100,d=60,center=true);
22
23Various block types don't need all of those parts, so they may look simpler:
24
25 // Topics: Mask, Cylindrical, Attachable
26
27Or:
28
29 // Description:
30 // This is a description.
31 // It can be multiple lines in length.
32
33Or:
34
35 // Usage: Typical Usage
36 // x = foo(a, b, c);
37 // x = foo([a, b, c, ...]);
38
39Comments blocks that don't start with a known block header are ignored and not added to output documentation. This lets you have normal comments in your code that are not used for documentation. If you must start a comment block with one of the known headers, then adding a single extra `/` or space after the comment marker, will make it be treated as a regular comment:
40
41 /// File: Foobar.scad
42
43
44Block Headers
45=======================
46
47File/LibFile Blocks
48-------------------
49
50All files must have either a `// File:` block or a `// LibFile:` block at the start. This is the place to put in the canonical filename, and a description of what the file is for. These blocks can be used interchangably, but you can only have one per file. `// File:` or `// LibFile:` blocks can be followed by a multiple line body that are added as markdown text after the header:
51
52 // LibFile: foo.scad
53 // You can have several lines of markdown formatted text here.
54 // You just need to make sure that each line is indented, with
55 // at least three spaces after the comment marker. You can
56 // denote a paragraph break with a comment line with three
57 // trailing spaces, or just a period.
58 // .
59 // You can have links in this text to functions, modules, or
60 // constants in other files by putting the name in double-
61 // braces like {{cyl()}} or {{lerp()}} or {{DOWN}}. If you want to
62 // link to another file, or section in another file you can use
63 // a manual markdown link like [Section: Cuboids](shapes.scad#section-cuboids).
64 // The end of the block is denoted by a line without a comment.
65
66Which outputs Markdown code that renders like:
67
68> ## LibFile: foo.scad
69> You can have several lines of markdown formatted text here.
70> You just need to make sure that each line is indented, with
71> at least three spaces after the comment marker. You can
72> denote a paragraph break with a comment line with three
73> trailing spaces, or just a period.
74>
75> You can have links in this text to functions, modules, or
76> constants in other files by putting the name in double-
77> braces like [cyl()](shapes.scad#functionmodule-cyl) or [lerp()](math.scad#function-lerp) or [DOWN](constants.scad-down). If you want to
78> link to another file, or section in another file you can use
79> a manual markdown link like [Section: Cuboids](shapes.scad#section-cuboids).
80> The end of the block is denoted by a line without a comment.
81
82You can use `// File:` instead of `// LibFile:`, if it seems more apropriate for your particular context:
83
84 // File: Foobar.scad
85 // This file contains a collection of metasyntactical nonsense.
86
87Which outputs Markdown code that renders like:
88
89> # File: Foobar.scad
90> This file contains a collection of metasyntactical nonsense.
91
92
93FileGroup Block
94---------------
95
96You can specify what group of files this .scad file is a part of with the `// FileGroup:` block:
97
98 // FileGroup: Advanced Modeling
99
100This affects the ordering of files in Table of Contents and CheatSheet files. This doesn't generate any output text otherwise.
101
102
103FileSummary Block
104-----------------
105
106You can give a short summary of the contents of this .scad file with the `// FileSummary:` block:
107
108 // FileSummary: Various modules to generate Foobar objects.
109
110This summary is used when summarizing this .scad file in the Table of Contents file. This will result in a line in the Table of Contents that renders like:
111
112> - [Foobar.scad](Foobar.scad): Various modules to generate Foobar objects.
113
114
115FileFootnotes Block
116-------------------
117
118You can specify footnotes that are appended to this .scad file's name wherever the list of files is shown, such as in the Table of Contents. You can do this with the `// FileFootnotes:` block. The syntax looks like:
119
120 // FileFootnotes: 1=First Footnote; 2=Second Footnote
121
122Multiple footnotes are separated by semicolons (`;`). Within each footnote, you specify the footnote symbol and the footnote text separated by an equals sign (`=`). The footnote symbol may be more than one character, like this:
123
124 // FileFootnotes: STD=Included in std.scad
125
126This will result in footnote markers that render like:
127
128> - Foobar.scad<sup id="fn_std">[STD](#footnote-std "Included in std.scad")</sup>
129
130
131Includes Block
132--------------
133
134To declare what code the user needs to add to their code to include or use this library file, you can use the `// Includes:` block. You should put this right after the `// File:` or `// LibFile:` block. This code block will also be prepended to all Example and Figure code blocks before they are evaluated:
135
136 // Includes:
137 // include <BOSL2/std.scad>
138 // include <BOSL2/beziers.scad>
139
140Which outputs Markdown code that renders like:
141
142> **Includes:**
143>
144> To use, add the following lines to the beginning of your file:
145>
146> ```openscad
147> include <BOSL2/std.scad>
148> include <BOSL2/beziers.scad>
149> ```
150
151
152CommonCode Block
153----------------
154
155If you have a block of code you plan to use throughout the file's Figure or Example blocks, and you don't actually want it displayed, you can use a `// CommonCode:` block like thus:
156
157 // CommonCode:
158 // module text3d(text, h=0.01, size=3) {
159 // linear_extrude(height=h, convexity=10) {
160 // text(text=text, size=size, valign="center", halign="center");
161 // }
162 // }
163
164This doesn't have immediately visible markdown output, but you *can* use that code in later examples:
165
166 // Example:
167 // text3d("Foobar");
168
169
170Section Block
171-------------
172
173Section blocks take a title, and an optional body that will be shown as the description of the Section. If a body line if just a `.` (dot, period), then that line is treated as a blank line in the output:
174
175 // Section: Foobar
176 // You can have several lines of markdown formatted text here.
177 // You just need to make sure that each line is indented, with
178 // at least three spaces after the comment marker. You can
179 // denote a paragraph break with a comment line with three
180 // trailing spaces, or just a period.
181 // .
182 // You can have links in this text to functions, modules, or
183 // constants in other files by putting the name in double-
184 // braces like {{cyl()}} or {{lerp()}} or {{DOWN}}. If you want to
185 // link to another file, or section in another file you can use
186 // a manual markdown link like [Section: Cuboids](shapes.scad#section-cuboids).
187 // .
188 // The end of the block is denoted by a line without a comment.
189 // or a line that is unindented after the comment.
190
191Which outputs Markdown code that renders like:
192
193> ## Section: Foobar
194> You can have several lines of markdown formatted text here.
195> You just need to make sure that each line is indented, with
196> at least three spaces after the comment marker. You can
197> denote a paragraph break with a comment line with three
198> trailing spaces, or just a period.
199>
200> You can have links in this text to functions, modules, or
201> constants in other files by putting the name in double-
202> braces like [cyl()](shapes.scad#functionmodule-cyl) or [lerp()](math.scad#function-lerp) or [DOWN](constants.scad-down). If you want to
203> link to another file, or section in another file you can use
204> a manual markdown link like [Section: Cuboids](shapes.scad#section-cuboids).
205>
206> The end of the block is denoted by a line without a comment.
207> or a line that is unindented after the comment.
208
209Sections can also include Figures; images generated from code that is not shown in a code block.
210
211
212Subsection Block
213----------------
214
215Subsection blocks take a title, and an optional body that will be shown as the description of the Subsection. A Subsection must be within a declared Section. If a body line is just a `.` (dot, period), then that line is treated as a blank line in the output:
216
217 // Subsection: Foobar
218 // You can have several lines of markdown formatted text here.
219 // You just need to make sure that each line is indented, with
220 // at least three spaces after the comment marker. You can
221 // denote a paragraph break with a comment line with three
222 // trailing spaces, or just a period.
223 // .
224 // You can have links in this text to functions, modules, or
225 // constants in other files by putting the name in double-
226 // braces like {{cyl()}} or {{lerp()}} or {{DOWN}}. If you want to
227 // link to another file, or section in another file you can use
228 // a manual markdown link like [Subsection: Foo](shapes.scad#subsection-foo).
229 // .
230 // The end of the block is denoted by a line without a comment.
231 // or a line that is unindented after the comment.
232
233Which outputs Markdown code that renders like:
234
235> ## Subsection: Foobar
236> You can have several lines of markdown formatted text here.
237> You just need to make sure that each line is indented, with
238> at least three spaces after the comment marker. You can
239> denote a paragraph break with a comment line with three
240> trailing spaces, or just a period.
241>
242> You can have links in this text to functions, modules, or
243> constants in other files by putting the name in double-
244> braces like [cyl()](shapes.scad#functionmodule-cyl) or [lerp()](math.scad#function-lerp) or [DOWN](constants.scad-down). If you want to
245> link to another file, or section in another file you can use
246> a manual markdown link like [Subsection: Foo](shapes.scad#subsection-foo).
247>
248> The end of the block is denoted by a line without a comment.
249> or a line that is unindented after the comment.
250
251Subsections can also include Figures; images generated from code that is not shown in a code block.
252
253
254Item Blocks
255-----------
256
257Item blocks headers come in four varieties: `Constant`, `Function`, `Module`, and `Function&Module`.
258
259The `Constant` header is used to document a code constant. It should have a Description sub-block, and Example sub-blocks are recommended:
260
261 // Constant: PHI
262 // Description: The golden ratio phi.
263 PHI = (1+sqrt(5))/2;
264
265Which outputs Markdown code that renders like:
266
267> ### Constant: PHI
268> **Description:**
269> The golden ration phi.
270
271
272The `Module` header is used to document a module. It should have a Description sub-block. It is recommended to also have Usage, Arguments, and Example/Examples sub-blocks. The Usage sub-block body lines are also used when constructing the Cheat Sheet index file:
273
274 // Module: cross()
275 // Usage:
276 // cross(size);
277 // Description:
278 // Creates a 2D cross/plus shape.
279 // Arguments:
280 // size = The scalar size of the cross.
281 // Example(2D):
282 // cross(size=100);
283 module cross(size=1) {
284 square([size, size/3], center=true);
285 square([size/3, size], center=true);
286 }
287
288Which outputs Markdown code that renders like:
289
290> ### Module: cross()
291> **Usage:**
292> - cross(size);
293>
294> **Description:**
295> Creates a 2D cross/plus shape.
296>
297> **Arguments:**
298> Positional Arg | What it does
299> -------------------- | -------------------
300> size | The scalar size of the cross.
301>
302> **Example:**
303> ```openscad
304> cross(size=100);
305> ```
306> GENERATED IMAGE GOES HERE
307
308
309The `Function` header is used to document a function. It should have a Description sub-block. It is recommended to also have Usage, Arguments, and Example/Examples sub-blocks. By default, Examples will not generate images for function blocks. Usage sub-block body lines are also used when constructing the Cheat Sheet index file:
310
311 // Function: vector_angle()
312 // Usage:
313 // ang = vector_angle(v1, v2);
314 // Description:
315 // Calculates the angle between two vectors in degrees.
316 // Arguments:
317 // v1 = The first vector.
318 // v2 = The second vector.
319 // Example:
320 // v1 = [1,1,0];
321 // v2 = [1,0,0];
322 // angle = vector_angle(v1, v2);
323 // // Returns: 45
324 function vector_angle(v1,v2) =
325 acos(max(-1,min(1,(vecs[0]*vecs[1])/(norm0*norm1))));
326
327Which outputs Markdown code that renders like:
328
329> ### Function: vector_angle()
330> **Usage:**
331> - ang = vector_angle(v1, v2);
332>
333> **Description:**
334> Calculates the angle between two vectors in degrees.
335>
336> **Arguments:**
337> Positional Arg | What it does
338> -------------------- | -------------------
339> `v1` | The first vector.
340> `v2` | The second vector.
341>
342> **Example:**
343> ```openscad
344> v1 = [1,1,0];
345> v2 = [1,0,0];
346> angle = vector_angle(v1, v2);
347> // Returns: 45
348> ```
349
350The `Function&Module` header is used to document a function which has a related module of the same name. It should have a Description sub-block. It is recommended to also have Usage, Arguments, and Example/Examples sub-blocks. You should have Usage blocks for both calling as a function, and calling as a module. Usage sub-block body lines are also used in constructing the Cheat Sheet index file:
351
352 // Function&Module: oval()
353 // Topics: 2D Shapes, Geometry
354 // Usage: As a Module
355 // oval(rx,ry);
356 // Usage: As a Function
357 // path = oval(rx,ry);
358 // Description:
359 // When called as a function, returns the perimeter path of the oval.
360 // When called as a module, creates a 2D oval shape.
361 // Arguments:
362 // rx = X axis radius.
363 // ry = Y axis radius.
364 // Example(2D): Called as a Function
365 // path = oval(100,60);
366 // polygon(path);
367 // Example(2D): Called as a Module
368 // oval(80,60);
369 module oval(rx,ry) {
370 polygon(oval(rx,ry));
371 }
372 function oval(rx,ry) =
373 [for (a=[360:-360/$fn:0.0001]) [rx*cos(a),ry*sin(a)];
374
375Which outputs Markdown code that renders like:
376
377> ### Function&Module: oval()
378> **Topics:** 2D Shapes, Geometry
379>
380> **Usage:** As a Module
381>
382> - oval(rx,ry);
383>
384> **Usage:** As a Function
385>
386> - path = oval(rx,ry);
387>
388> **Description:**
389> When called as a function, returns the perimeter path of the oval.
390> When called as a module, creates a 2D oval shape.
391>
392> **Arguments:**
393> Positional Arg | What it does
394> -------------------- | -------------------
395> rx | X axis radius.
396> ry | Y axis radius.
397>
398> **Example:** Called as a Function
399>
400> ```openscad
401> path = oval(100,60);
402> polygon(path);
403> ```
404> GENERATED IMAGE SHOWN HERE
405>
406> **Example:** Called as a Module
407>
408> ```openscad
409> oval(80,60);
410> ```
411> GENERATED IMAGE SHOWN HERE
412
413These Type blocks can have a number of sub-blocks. Most sub-blocks are optional, The available standard sub-blocks are:
414
415- `// Aliases: alternatename(), anothername()`
416- `// Status: DEPRECATED`
417- `// Topics: Comma, Delimited, Topic, List`
418- `// Usage:`
419- `// Description:`
420- `// Figure:` or `// Figures`
421- `// Continues:`
422- `// Arguments:`
423- `// See Also: otherfunc(), othermod(), OTHERCONST`
424- `// Example:` or `// Examples:`
425
426
427Aliases Block
428-------------
429
430The Aliases block is used to give alternate names for a function, module, or
431constant. This is reflected in the indexes generated. It looks like:
432
433 // Aliases: secondname(), thirdname()
434
435Which outputs Markdown code that renders like:
436
437> **Aliases:** secondname(), thirdname()
438
439
440Status Block
441------------
442
443The Status block is used to mark a function, module, or constant as deprecated:
444
445 // Status: DEPRECATED, use foo() instead
446
447Which outputs Markdown code that renders like:
448
449> **Status:** DEPRECATED, use foo() instead
450
451
452Topics Block
453------------
454
455The Topics block can associate various topics with the current function or module. This can be used to make an index of Topics:
456
457 // Topics: 2D Shapes, Geometry, Masks
458
459Which outputs Markdown code that renders like:
460
461> **Topics:** 2D Shapes, Geometry, Masks
462
463
464Usage Block
465-----------
466
467The Usage block describes the various ways that the current function or module can be called, with the names of the arguments. By convention, the first few arguments that can be called positionally just have their name shown. The remaining arguments that should be passed by name, will have the name followed by an `=` (equal sign). Arguments that are optional in the given Usage context are shown in `[` and `]` angle brackets. Usage sub-block body lines are also used when constructing the Cheat Sheet index file:
468
469 // Usage: As a Module
470 // oval(rx, ry, <spin=>);
471 // Usage: As a Function
472 // path = oval(rx, ry, <spin=>);
473
474Which outputs Markdown code that renders like:
475
476> **Usage:** As a Module
477> - oval(rx, ry, <spin=>);
478>
479> **Usage:** As a Function
480>
481> - path = oval(rx, ry, <spin=>);
482
483
484Description Block
485-----------------
486The Description block just describes the currect function, module, or constant:
487
488 // Descripton: This is the description for this function or module.
489 // It can be multiple lines long. Markdown syntax code will be used
490 // verbatim in the output markdown file, with the exception of `_`,
491 // which will traslate to `\_`, so that underscores in function/module
492 // names don't get butchered. A line with just a period (`.`) will be
493 // treated as a blank line.
494 // .
495 // You can have links in this text to functions, modules, or
496 // constants in other files by putting the name in double-
497 // braces like {{cyl()}} or {{lerp()}} or {{DOWN}}. If you want to
498 // link to another file, or section in another file you can use
499 // a manual markdown link like [Section: Cuboids](shapes.scad#section-cuboids).
500
501Which outputs Markdown code that renders like:
502
503> **Description:**
504> It can be multiple lines long. Markdown syntax code will be used
505> verbatim in the output markdown file, with the exception of `_`,
506> which will traslate to `\_`, so that underscores in function/module
507> names don't get butchered. A line with just a period (`.`) will be
508> treated as a blank line.
509>
510> You can have links in this text to functions, modules, or
511> constants in other files by putting the name in double-
512> braces like [cyl()](shapes.scad#functionmodule-cyl) or [lerp()](math.scad#function-lerp) or [DOWN](constants.scad-down). If you want to
513> link to another file, or section in another file you can use
514> a manual markdown link like [Section: Cuboids](shapes.scad#section-cuboids).
515
516
517Continues Block
518---------------
519The Continues block can be used to continue the body text of a previous block that has been interrupted by a Figure:
520
521 // Descripton: This is the description for this function or module. It can be
522 // many lines long. If you need to show an image in the middle of this text,
523 // you can use a Figure, like this:
524 // Figure(2D): A circle with a square cutout.
525 // difference() {
526 // circle(d=100);
527 // square(100/sqrt(2), center=true);
528 // }
529 // Continues: You can continue the description text here. It can also be
530 // multiple lines long. This continuation will not print a header.
531
532Which outputs Markdown code that renders like:
533
534> **Descripton:**
535> This is the description for this function or module. It can be
536> many lines long. If you need to show an image in the middle of this text,
537> you can use a Figure, like this:
538>
539> **Figure 1:** A circle with a square cutout.
540> GENERATED IMAGE SHOWN HERE
541>
542> You can continue the description text here. It can also be
543> multiple lines long. This continuation will not print a header.
544>
545
546
547Arguments Block
548---------------
549The Arguments block creates a table that describes the positional arguments for a function or module, and optionally a second table that describes named arguments:
550
551 // Arguments:
552 // v1 = This supplies the first vector.
553 // v2 = This supplies the second vector.
554 // ---
555 // fast = Use fast, but less comprehensive calculation method.
556 // bar = Takes an optional `bar` struct. See {{bar()}}.
557 // dflt = Default value.
558
559Which outputs Markdown code that renders like:
560
561> **Arguments:**
562> Positional Arg | What it Does
563> -------------- | ---------------------------------
564> `v1` | This supplies the first vector.
565> `v2` | The supplies the second vector.
566>
567> Named Arg | What it Does
568> -------------- | ---------------------------------
569> `fast` | If true, use fast, but less accurate calculation method.
570> `bar` | Takes an optional `bar` struct. See [bar()](foobar.scad#function-bar).
571> `dflt` | Default value.
572
573
574See Also Block
575--------------
576
577The See Also block is used to give links to related functions, modules, or
578constants. It looks like:
579
580 // See Also: relatedfunc(), similarmodule()
581
582Which outputs Markdown code that renders like:
583
584> **See Also:** [relatedfunc()](otherfile.scad#relatedfunc), [similarmodule()](otherfile.scad#similarmodule)
585
586
587Figure Block
588--------------
589
590A Figure block generates and shows an image from a script in the multi-line body, by running it in OpenSCAD. A Figures block (plural) does the same, but treats each line of the body as a separate Figure block:
591
592 // Figure: Figure description
593 // cylinder(h=100, d1=75, d2=50);
594 // up(100) cylinder(h=100, d1=50, d2=75);
595 // Figure(Spin,VPD=444): Animated figure that spins to show all faces.
596 // cube([10,100,50], center=true);
597 // cube([100,10,30], center=true);
598 // Figures:
599 // cube(100);
600 // cylinder(h=100,d=50);
601 // sphere(d=100);
602
603Which outputs Markdown code that renders like:
604
605> **Figure 1:** Figure description
606> GENERATED IMAGE SHOWN HERE
607>
608> **Figure 2:** Animated figure that spins to show all faces.
609> GENERATED IMAGE SHOWN HERE
610>
611> **Figure 3:**
612> GENERATED IMAGE OF CUBE SHOWN HERE
613>
614> **Figure 4:**
615> GENERATED IMAGE OF CYLINDER SHOWN HERE
616>
617> **Figure 5:**
618> GENERATED IMAGE OF SPHERE SHOWN HERE
619
620The metadata of the Figure block can contain various directives to alter how
621the image will be generated. These can be comma separated to give multiple
622metadata directives:
623
624- `NORENDER`: Don't generate an image for this example, but show the example text.
625- `Hide`: Generate, but don't show script or image. This can be used to generate images to be manually displayed in markdown text blocks.
626- `2D`: Orient camera in a top-down view for showing 2D objects.
627- `3D`: Orient camera in an oblique view for showing 3D objects.
628- `VPD=440`: Force viewpoint distance `$vpd` to 440.
629- `VPT=[10,20,30]` Force the viewpoint translation `$vpt` to `[10,20,30]`.
630- `VPR=[55,0,600]` Force the viewpoint rotation `$vpr` to `[55,0,60]`.
631- `Spin`: Animate camera orbit around the `[0,1,1]` axis to display all sides of an object.
632- `FlatSpin`: Animate camera orbit around the Z axis, above the XY plane.
633- `Anim`: Make an animation where `$t` varies from `0.0` to almost `1.0`.
634- `Frames=36`: Number of animation frames to make.
635- `FrameMS=250`: Sets the number of milliseconds per frame for spins and animation.
636- `FPS=8`: Sets the number of frames per second for spins and animation.
637- `Small`: Make the image small sized.
638- `Med`: Make the image medium sized.
639- `Big`: Make the image big sized.
640- `Huge`: Make the image huge sized.
641- `Size=880x640`: Make the image 880 by 640 pixels in size.
642- `ThrownTogether`: Render in Thrown Together view mode instead of Preview mode.
643- `Render`: Force full rendering from OpenSCAD, instead of the normal Preview mode.
644- `Edges`: Highlight face edges.
645- `NoAxes`: Hides the axes and scales.
646- `NoScales`: Hides the scale numbers along the axes.
647- `ScriptUnder`: Display script text under image, rather than beside it.
648
649
650Example Block
651-------------
652
653An Example block shows a script, and possibly shows an image generated from it.
654The script is in the multi-line body. The `Examples` (plural) block does
655the same, but it treats eash body line as a separate Example bloc to show.
656Any images, if generated, will be created by running it in OpenSCAD:
657
658 // Example: Example description
659 // cylinder(h=100, d1=75, d2=50);
660 // up(100) cylinder(h=100, d1=50, d2=75);
661 // Example(Spin,VPD=444): Animated shape that spins to show all faces.
662 // cube([10,100,50], center=true);
663 // cube([100,10,30], center=true);
664 // Examples:
665 // cube(100);
666 // cylinder(h=100,d=50);
667 // sphere(d=100);
668
669Which outputs Markdown code that renders like:
670
671> **Example 1:** Example description
672> ```openscad
673> cylinder(h=100, d1=75, d2=50);
674> up(100) cylinder(h=100, d1=50, d2=75);
675> ```
676> GENERATED IMAGE SHOWN HERE
677>
678> **Example 2:** Animated shape that spins to show all faces.
679> ```openscad
680> cube([10,100,50], center=true);
681> cube([100,10,30], center=true);
682> ```
683> GENERATED IMAGE SHOWN HERE
684>
685> **Example 3:**
686> ```openscad
687> cube(100);
688> ```
689> GENERATED IMAGE OF CUBE SHOWN HERE
690>
691> **Example 4:**
692> ```openscad
693> cylinder(h=100,d=50);
694> ```
695> GENERATED IMAGE OF CYLINDER SHOWN HERE
696>
697> **Example 5:**
698> ```openscad
699> sphere(d=100);
700> ```
701> GENERATED IMAGE OF SPHERE SHOWN HERE
702
703The metadata of the Example block can contain various directives to alter how
704the image will be generated. These can be comma separated to give multiple
705metadata directives:
706
707- `NORENDER`: Don't generate an image for this example, but show the example text.
708- `Hide`: Generate, but don't show script or image. This can be used to generate images to be manually displayed in markdown text blocks.
709- `2D`: Orient camera in a top-down view for showing 2D objects.
710- `3D`: Orient camera in an oblique view for showing 3D objects. Often used to force an Example sub-block to generate an image in Function and Constant blocks.
711- `VPD=440`: Force viewpoint distance `$vpd` to 440.
712- `VPT=[10,20,30]` Force the viewpoint translation `$vpt` to `[10,20,30]`.
713- `VPR=[55,0,600]` Force the viewpoint rotation `$vpr` to `[55,0,60]`.
714- `Spin`: Animate camera orbit around the `[0,1,1]` axis to display all sides of an object.
715- `FlatSpin`: Animate camera orbit around the Z axis, above the XY plane.
716- `Anim`: Make an animation where `$t` varies from `0.0` to almost `1.0`.
717- `FrameMS=250`: Sets the number of milliseconds per frame for spins and animation.
718- `Frames=36`: Number of animation frames to make.
719- `Small`: Make the image small sized.
720- `Med`: Make the image medium sized.
721- `Big`: Make the image big sized.
722- `Huge`: Make the image huge sized.
723- `Size=880x640`: Make the image 880 by 640 pixels in size.
724- `Render`: Force full rendering from OpenSCAD, instead of the normal preview.
725- `Edges`: Highlight face edges.
726- `NoAxes`: Hides the axes and scales.
727- `ScriptUnder`: Display script text under image, rather than beside it.
728
729Modules will default to generating and displaying the image as if the `3D`
730directive is given. Functions and constants will default to not generating
731an image unless `3D`, `Spin`, `FlatSpin` or `Anim` is explicitly given.
732
733If any lines of the Example script begin with `--`, then they are not shown in
734the example script output to the documentation, but they *are* included in the
735script used to generate the example image, without the `--`, of course:
736
737 // Example: Multi-line example.
738 // --$fn = 72; // Lines starting with -- aren't shown in docs example text.
739 // lst = [
740 // "multi-line examples",
741 // "are shown in one block",
742 // "with a single image.",
743 // ];
744 // foo(lst, 23, "blah");
745
746
747Creating Custom Block Headers
748=============================
749
750If you have need of a non-standard documentation block in your docs, you can declare the new block type using `DefineHeader:`. This has the syntax:
751
752 // DefineHeader(TYPE): NEWBLOCKNAME
753
754or:
755
756 // DefineHeader(TYPE;OPTIONS): NEWBLOCKNAME
757
758Where NEWBLOCKNAME is the name of the new block header, OPTIONS is an optional list of zero or more semicolon-separated header options, and TYPE defines the behavior of the new block. TYPE can be one of:
759
760- `Generic`: Show both the TitleText and body.
761- `Text`: Show the TitleText as the first line of the body.
762- `Headerless`: Show the TitleText as the first line of the body, with no header line.
763- `Label`: Show only the TitleText and no body.
764- `NumList`: Shows TitleText, and the body lines in a numbered list.
765- `BulletList`: Shows TitleText, and the body lines in a bullet list.
766- `Table`: Shows TitleText, and body lines in a definition table.
767- `Figure`: Shows TitleText, and an image rendered from the script in the Body.
768- `Example`: Like Figure, but also shows the body as an example script.
769
770The OPTIONS are zero or more semicolon separated options for defining the header options. Some of them only require the option name, like `Foo`, and some have an option name and a value separated by an equals sign, like `Foo=Bar`. There is currently only one option common to all header types:
771
772- `ItemOnly`: Specify that the new header is only allowed as part of the documentation block for a Constant, Function, or Module.
773
774Generic Block Type
775------------------
776
777The Generic block header type takes both title and body lines and generates a markdown block that has the block header, title, and a following body:
778
779 // DefineHeader(Generic): Result
780 // Result: For Typical Cases
781 // Does typical things.
782 // Or something like that.
783 // Refer to {{stuff()}} for more info.
784 // Result: For Atypical Cases
785 // Performs an atypical thing.
786
787Which outputs Markdown code that renders like:
788
789> **Result:** For Typical Cases
790>
791> Does typical things.
792> Or something like that.
793> Refer to [stuff()](foobar.scad#function-stuff) for more info.
794>
795> **Result:** For Atypical Cases
796>
797> Performs an atypical thing.
798>
799
800
801Text Block Type
802---------------
803
804The Text block header type is similar to the Generic type, except it merges the title into the body. This is useful for allowing single-line or multi-line blocks:
805
806 // DefineHeader(Text): Reason
807 // Reason: This is a simple reason.
808 // Reason: This is a complex reason.
809 // It is a multi-line explanation
810 // about why this does what it does.
811 // Refer to {{nonsense()}} for more info.
812
813Which outputs Markdown code that renders like:
814
815> **Reason:**
816>
817> This is a simple reason.
818>
819> **Reason:**
820>
821> This is a complex reason.
822> It is a multi-line explanation
823> about why this does what it does.
824> Refer to [nonsense()](foobar.scad#function-nonsense) for more info.
825>
826
827Headerless Block Type
828---------------------
829
830The Headerless block header type is similar to the Generic type, except it merges the title into the body, and generates no header line.
831
832 // DefineHeader(Headerless): Explanation
833 // Explanation: This is a simple explanation.
834 // Explanation: This is a complex explanation.
835 // It is a multi-line explanation
836 // about why this does what it does.
837 // Refer to {{nonsense()}} for more info.
838
839Which outputs Markdown code that renders like:
840
841> This is a simple explanation.
842>
843> This is a complex explanation.
844> It is a multi-line explanation
845> about why this does what it does.
846> Refer to [nonsense()](foobar.scad#function-nonsense) for more info.
847>
848
849
850Label Block Type
851----------------
852
853The Label block header type takes just the title, and shows it with the header:
854
855 // DefineHeader(Label): Regions
856 // Regions: Antarctica, New Zealand
857 // Regions: Europe, Australia
858
859Which outputs Markdown code that renders like:
860
861> **Regions:** Antarctica, New Zealand
862> **Regions:** Europe, Australia
863
864
865NumList Block Type
866------------------
867
868The NumList block header type takes both title and body lines, and outputs a
869numbered list block:
870
871 // DefineHeader(NumList): Steps
872 // Steps: How to handle being on fire.
873 // Stop running around and panicing.
874 // Drop to the ground. Refer to {{drop()}}.
875 // Roll on the ground to smother the flames.
876
877Which outputs Markdown code that renders like:
878
879> **Steps:** How to handle being on fire.
880>
881> 1. Stop running around and panicing.
882> 2. Drop to the ground. Refer to [drop()](foobar.scad#function-drop).
883> 3. Roll on the ground to smother the flames.
884>
885
886
887BulletList Block Type
888---------------------
889
890The BulletList block header type takes both title and body lines:
891
892 // DefineHeader(BulletList): Side Effects
893 // Side Effects: For Typical Uses
894 // The variable {{$foo}} gets set.
895 // The default for subsequent calls is updated.
896
897Which outputs Markdown code that renders like:
898
899> **Side Effects:** For Typical Uses
900>
901> - The variable [$foo](foobar.scad#function-foo) gets set.
902> - The default for subsequent calls is updated.
903>
904
905
906Table Block Type
907----------------
908
909The Table block header type outputs a header block with the title, followed by one or more tables. This is generally meant for definition lists. The header names are given as the `Headers=` option in the DefineHeader metadata. Header names are separated by `|` (vertical bar, or pipe) characters, and sets of headers (for multiple tables) are separated by `||` (two vertical bars). A header that starts with the `^` (hat, or circumflex) character, will cause the items in that column to be surrounded by \`foo\` literal markers. Cells in the body content are separated by `=` (equals signs):
910
911 // DefineHeader(Table;Headers=^Link Name|Description): Anchors
912 // Anchors: by Name
913 // "link1" = Anchor for the joiner Located at the {{BACK}} side of the shape.
914 // "a"/"b" = Anchor for the joiner Located at the {{FRONT}} side of the shape.
915
916Which outputs Markdown code that renders like:
917
918> **Anchors:** by Name
919>
920> Link Name | Description
921> -------------- | --------------------
922> `"link1"` | Anchor for the joiner at the [BACK](constants.scad#constant-back) side of the shape.
923> `"a"` / `"b"` | Anchor for the joiner at the [FRONT](constants.scad#constant-front) side of the shape.
924>
925
926You can have multiple subtables, separated by a line with only three dashes: `---`:
927
928 // DefineHeader(Table;Headers=^Pos Arg|What it Does||^Names Arg|What it Does): Args
929 // Args:
930 // foo = The foo argument.
931 // bar = The bar argument.
932 // ---
933 // baz = The baz argument.
934 // qux = The baz argument.
935
936Which outputs Markdown code that renders like:
937
938> **Args:**
939>
940> Pos Arg | What it Does
941> ----------- | --------------------
942> `foo` | The foo argument.
943> `bar` | The bar argument.
944>
945> Named Arg | What it Does
946> ----------- | --------------------
947> `baz` | The baz argument.
948> `qux` | The qux argument.
949>
950
951
952Defaults Configuration
953======================
954
955The `openscad_decsgen` script looks for an `.openscad_docsgen_rc` file in the source code directory it is run in. In that file, you can give a few defaults for what files will be processed, and where to save the generated documentation.
956
957---
958
959To specify what directory to write the output documentation to, you can use the DocsDirectory block:
960
961 DocsDirectory: wiki_dir
962
963---
964
965To specify what target profile to output for, use the TargetProfile block. You must specify either `wiki` or `githubwiki` as the value:
966
967 TargetProfile: githubwiki
968
969---
970
971To specify what the project name is, use the ProjectName block, like this:
972
973 ProjectName: My Project Name
974
975---
976
977To specify what types of files will be generated, you can use the GenerateDocs block. You give it a comma separated list of docs file types like this:
978
979 GenerateDocs: Files, ToC, Index, Topics, CheatSheet, Sidebar
980
981Where the valid docs file types are as follows:
982
983- `Files`: Generate a documentation file for each .scad input file. Generates Images.
984- `ToC`: Generate a project-wide Table of Contents file.
985- `Index`: Generate an alphabetically sorted function/module/constants index file.
986- `Topics`: Generate an index file of topics, sorted alphabetically.
987- `CheatSheet`: Generate a CheatSheet summary of function/module Usages.
988- `Cheat`: The same as `CheatSheet`.
989- `Sidebar`: Generate a \_Sidebar index of files.
990
991---
992
993To ignore specific files, to prevent generating documentation for them, you can use the IgnoreFiles block. Note that the commentline prefix is not needed in the configuration file:
994
995 IgnoreFiles:
996 ignored1.scad
997 ignored2.scad
998 tmp_*.scad
999
1000---
1001
1002To prioritize the ordering of files when generating the Table of Contents and other indices, you can use the PrioritizeFiles block:
1003
1004 PrioritizeFiles:
1005 file1.scad
1006 file2.scad
1007
1008---
1009
1010You can also use the DefineHeader block in the config file to make custom block headers:
1011
1012 DefineHeader(Text;ItemOnly): Returns
1013 DefineHeader(BulletList): Side Effects
1014 DefineHeader(Table;Headers=^Anchor Name|Position): Extra Anchors
1015
1016
1017