- 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
You can specify what group of files this .scad file is a part of with the `// FileGroup:` block:
// FileGroup: Advanced Modeling
This affects the ordering of files in Table of Contents and CheatSheet files. This doesn't generate any output text otherwise.
FileSummary Block
-----------------
You can give a short summary of the contents of this .scad file with the `// FileSummary:` block:
// FileSummary: Various modules to generate Foobar objects.
This 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:
> - [Foobar.scad](Foobar.scad): Various modules to generate Foobar objects.
FileFootnotes Block
-------------------
You 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:
Multiple 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:
// FileFootnotes: STD=Included in std.scad
This will result in footnote markers that render like:
> - Foobar.scad<sup id="fn_std">[STD](#footnote-std "Included in std.scad")</sup>
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:
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:
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
Subsection 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:
// Subsection: 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.
// .
// You can have links in this text to functions, modules, or
// constants in other files by putting the name in double-
// braces like {{cyl()}} or {{lerp()}} or {{DOWN}}. If you want to
// link to another file, or section in another file you can use
// a manual markdown link like [Subsection: Foo](shapes.scad#subsection-foo).
// .
// 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:
> ## Subsection: 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.
>
> You can have links in this text to functions, modules, or
> constants in other files by putting the name in double-
> braces like [cyl()](shapes.scad#functionmodule-cyl) or [lerp()](math.scad#function-lerp) or [DOWN](constants.scad-down). If you want to
> link to another file, or section in another file you can use
> a manual markdown link like [Subsection: Foo](shapes.scad#subsection-foo).
>
> The end of the block is denoted by a line without a comment.
> or a line that is unindented after the comment.
Subsections can also include Figures; images generated from code that is not shown in a code block.
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. The Usage sub-block body lines are also used when constructing the Cheat Sheet index file:
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. Usage sub-block body lines are also used when constructing the Cheat Sheet index file:
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. Usage sub-block body lines are also used in constructing the Cheat Sheet index file:
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 sub-block body lines are also used when constructing the Cheat Sheet index file:
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.
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.
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]`.
Where 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:
The 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:
-`ItemOnly`: Specify that the new header is only allowed as part of the documentation block for a Constant, Function, or Module.
The 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:
The 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):
The `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.
---
To specify what directory to write the output documentation to, you can use the DocsDirectory block:
DocsDirectory: wiki_dir
---
To specify what target profile to output for, use the TargetProfile block. You must specify either `wiki` or `githubwiki` as the value:
TargetProfile: githubwiki
---
To specify what the project name is, use the ProjectName block, like this:
-`Files`: Generate a documentation file for each .scad input file. Generates Images.
-`ToC`: Generate a project-wide Table of Contents file.
-`Index`: Generate an alphabetically sorted function/module/constants index file.
-`Topics`: Generate an index file of topics, sorted alphabetically.
-`CheatSheet`: Generate a CheatSheet summary of function/module Usages.
-`Cheat`: The same as `CheatSheet`.
-`Sidebar`: Generate a \_Sidebar index of files.
---
To 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:
