- The Block Name is one or two words, both starting with a capital letter.
- 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.
- A colon `:` will always follow after the Block Name and optional Metadata.
- 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.
- The body will contain zero or more lines of text indented by three spaces after the comment markers. Each line can contain arbitrary text.
Comments 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:
All 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:
// LibFile: foo.scad
// You can have several lines of markdown formatted text here.
// You just need to make sure that each line is indented, with
// at least three spaces after the comment marker. You can
// denote a paragraph break with a comment line with three
// trailing spaces, or just a period.
// .
// The end of the block is denoted by a line without a comment.
Which outputs Markdown code that renders like:
> ## LibFile: foo.scad
> You can have several lines of markdown formatted text here.
> You just need to make sure that each line is indented, with
> at least three spaces after the comment marker. You can
> denote a paragraph break with a comment line with three
> trailing spaces, or just a period.
>
> The end of the block is denoted by a line without a comment.
Or:
// File: Foobar.scad
// This file contains a collection of metasyntactical nonsense.
Which outputs Markdown code that renders like:
> # File: Foobar.scad
> This file contains a collection of metasyntactical nonsense.
Includes Block
--------------
To 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:
// Includes:
// include <BOSL2/std.scad>
// include <BOSL2/beziers.scad>
Which outputs Markdown code that renders like:
> **Includes:**
>
> To use, add the following lines to the beginning of your file:
>
> ```openscad
> include <BOSL2/std.scad>
> include <BOSL2/beziers.scad>
> ```
CommonCode Block
----------------
If 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:
This doesn't have immediately visible markdown output, but you *can* use that code in later examples:
// Example:
// text3d("Foobar");
Section Block
-------------
Section 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:
// Section: Foobar
// You can have several lines of markdown formatted text here.
// You just need to make sure that each line is indented, with
// at least three spaces after the comment marker. You can
// denote a paragraph break with a comment line with three
// trailing spaces, or just a period.
// .
// The end of the block is denoted by a line without a comment.
// or a line that is unindented after the comment.
Which outputs Markdown code that renders like:
>## Section: Foobar
>You can have several lines of markdown formatted text here.
>You just need to make sure that each line is indented, with
>at least three spaces after the comment marker. You can
>denote a paragraph break with a comment line with three
>trailing spaces, or just a period.
>
>The end of the block is denoted by a line without a comment.
Item blocks headers come in four varieties: `Constant`, `Function`, `Module`, and `Function&Module`.
The `Constant` header is used to document a code constant. It should have a Description sub-block, and Example sub-blocks are recommended:
// Constant: PHI
// Description: The golden ratio phi.
PHI = (1+sqrt(5))/2;
Which outputs Markdown code that renders like:
>### Constant: PHI
>**Description:**
>The golden ration phi.
The `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:
// Module: cross()
// Usage:
// cross(size);
// Description:
// Creates a 2D cross/plus shape.
// Arguments:
// size = The scalar size of the cross.
// Example(2D):
// cross(size=100);
module cross(size=1) {
square([size, size/3], center=true);
square([size/3, size], center=true);
}
Which outputs Markdown code that renders like:
>### Module: cross()
>**Usage:**
>- cross(size);
>
>**Description:**
>Creates a 2D cross/plus shape.
>
>**Arguments:**
>Positional Arg | What it does
>-------------------- | -------------------
>size | The scalar size of the cross.
>
>**Example:**
>```openscad
>cross(size=100);
>```
>GENERATED IMAGE GOES HERE
The `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:
// Function: vector_angle()
// Usage:
// ang = vector_angle(v1, v2);
// Description:
// Calculates the angle between two vectors in degrees.
>Calculates the angle between two vectors in degrees.
>
>**Arguments:**
>Positional Arg | What it does
>-------------------- | -------------------
>`v1` | The first vector.
>`v2` | The second vector.
>
>**Example:**
>```openscad
>v1 = [1,1,0];
>v2 = [1,0,0];
>angle = vector_angle(v1, v2);
>// Returns: 45
>```
The `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:
// Function&Module: oval()
// Topics: 2D Shapes, Geometry
// Usage: As a Module
// oval(rx,ry);
// Usage: As a Function
// path = oval(rx,ry);
// Description:
// When called as a function, returns the perimeter path of the oval.
// When called as a module, creates a 2D oval shape.
>When called as a function, returns the perimeter path of the oval.
>When called as a module, creates a 2D oval shape.
>
>**Arguments:**
>Positional Arg | What it does
>-------------------- | -------------------
>rx | X axis radius.
>ry | Y axis radius.
>
>**Example:** Called as a Function
>
>```openscad
>path = oval(100,60);
>polygon(path);
>```
>GENERATED IMAGE SHOWN HERE
>
>**Example:** Called as a Module
>
>```openscad
>oval(80,60);
>```
>GENERATED IMAGE SHOWN HERE
These Type blocks can have a number of sub-blocks. Most sub-blocks are optional, The available standard sub-blocks are:
-`// Status: DEPRECATED`
-`// Topics: Comma, Delimited, Topic, List`
-`// Usage:`
-`// Description:`
-`// Arguments:`
-`// Figure:` or `// Figures`
-`// Example:` or `// Examples:`
Status Block
------------
The Status block is used to mark a function, module, or constant as deprecated:
// Status: DEPRECATED, use foo() instead
Which outputs Markdown code that renders like:
>**Status:** DEPRECATED, use foo() instead
Topics Block
------------
The Topics block can associate various topics with the current function or module. This can be used to make an index of Topics:
// Topics: 2D Shapes, Geometry, Masks
Which outputs Markdown code that renders like:
>**Topics:** 2D Shapes, Geometry, Masks
Usage Block
-----------
The 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: As a Module
// oval(rx, ry, <spin=>);
// Usage: As a Function
// path = oval(rx, ry, <spin=>);
Which outputs Markdown code that renders like:
>**Usage:** As a Module
>- oval(rx, ry, <spin=>);
>
>**Usage:** As a Function
>
>- path = oval(rx, ry, <spin=>);
Description Block
-----------------
The Description block just describes the currect function, module, or constant:
// Descripton: This is the description for this function or module.
// It can be multiple lines long. Markdown syntax code will be used
// verbatim in the output markdown file, with the exception of `_`,
// which will traslate to `\_`, so that underscores in function/module
// names don't get butchered.
Which outputs Markdown code that renders like:
>**Description:**
>It can be multiple lines long. Markdown syntax code will be used
>verbatim in the output markdown file, with the exception of `_`,
>which will traslate to `\_`, so that underscores in function/module
>names don't get butchered.
Arguments Block
---------------
The Arguments block creates a table that describes the positional arguments for a function or module, and optionally a second table that describes named arguments:
// Arguments:
// v1 = This supplies the first vector.
// v2 = This supplies the second vector.
// ---
// fast = Use fast, but less comprehensive calculation method.
>`fast` | If true, use fast, but less accurate calculation method.
>`dflt` | Default value.
---
Figure Block
--------------
A 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:
// Figure: Figure description
// cylinder(h=100, d1=75, d2=50);
// up(100) cylinder(h=100, d1=50, d2=75);
// Figure(Spin,VPD=444): Animated figure that spins to show all faces.
// cube([10,100,50], center=true);
// cube([100,10,30], center=true);
// Figures:
// cube(100);
// cylinder(h=100,d=50);
// sphere(d=100);
Which outputs Markdown code that renders like:
>**Figure 1:** Figure description
>GENERATED IMAGE SHOWN HERE
>
>**Figure 2:** Animated figure that spins to show all faces.
>GENERATED IMAGE SHOWN HERE
>
>**Figure 3:**
>GENERATED IMAGE OF CUBE SHOWN HERE
>
>**Figure 4:**
>GENERATED IMAGE OF CYLINDER SHOWN HERE
>
>**Figure 5:**
>GENERATED IMAGE OF SPHERE SHOWN HERE
The metadata of the Figure block can contain various directives to alter how
the image will be generated. These can be comma separated to give multiple
-`Size=880x640`: Make the image 880 by 640 pixels in size.
-`Render`: Force full rendering from OpenSCAD, instead of the normal preview.
-`Edges`: Highlight face edges.
-`NoAxes`: Hides the axes and scales.
Example Block
-------------
An Example block shows a script, and possibly shows an image generated from it.
The script is in the multi-line body. The `Examples` (plural) block does
the same, but it treats eash body line as a separate Example bloc to show.
Any images, if generated, will be created by running it in OpenSCAD:
// Example: Example description
// cylinder(h=100, d1=75, d2=50);
// up(100) cylinder(h=100, d1=50, d2=75);
// Example(Spin,VPD=444): Animated shape that spins to show all faces.
// cube([10,100,50], center=true);
// cube([100,10,30], center=true);
// Examples:
// cube(100);
// cylinder(h=100,d=50);
// sphere(d=100);
Which outputs Markdown code that renders like:
>**Example 1:** Example description
>```openscad
>cylinder(h=100, d1=75, d2=50);
>up(100) cylinder(h=100, d1=50, d2=75);
>```
>GENERATED IMAGE SHOWN HERE
>
>**Example 2:** Animated shape that spins to show all faces.
>```openscad
>cube([10,100,50], center=true);
>cube([100,10,30], center=true);
>```
>GENERATED IMAGE SHOWN HERE
>
>**Example 3:**
>```openscad
>cube(100);
>```
>GENERATED IMAGE OF CUBE SHOWN HERE
>
>**Example 4:**
>```openscad
>cylinder(h=100,d=50);
>```
>GENERATED IMAGE OF CYLINDER SHOWN HERE
>
>**Example 5:**
>```openscad
>sphere(d=100);
>```
>GENERATED IMAGE OF SPHERE SHOWN HERE
The metadata of the Example block can contain various directives to alter how
the image will be generated. These can be comma separated to give multiple
metadata directives:
-`NORENDER`: Don't generate an image for this example, but show the example text.
-`Hide`: Generate, but don't show script or image. This can be used to generate images to be manually displayed in markdown text blocks.
-`2D`: Orient camera in a top-down view for showing 2D objects.
-`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.
-`VPD=440`: Force viewpoint distance `$vpd` to 440.
-`VPT=[10,20,30]` Force the viewpoint translation `$vpt` to `[10,20,30]`.
-`VPR=[55,0,600]` Force the viewpoint rotation `$vpr` to `[55,0,60]`.
