477 lines
13 KiB
Plaintext
477 lines
13 KiB
Plaintext
_section: Flatworm Docs @<flatworm>
|
|
|
|
The //Flatworm Docs// rendering engine is designed to be **very**
|
|
simple, but provide enough formatting necessary for documenting
|
|
JavaScript libraries.
|
|
|
|
A lot of its inspiration came from [Read the Docs](link-rtd) and
|
|
the [Sphinx](link-sphinx) project.
|
|
|
|
|
|
_subsection: Fragments @<flatworm-fragments>
|
|
|
|
Each page is made up of fragments. A fragment is a [directive](flatworm-directive),
|
|
with an value and optional //link//, //extensions// and a body.
|
|
|
|
Many directives support [markdown](flatworm-markdown) in their value and body.
|
|
|
|
A fragment's body continues until another fragment is encountered.
|
|
|
|
|
|
_heading: Directive Format
|
|
|
|
_code: @lang<text>
|
|
|
|
\_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER>
|
|
BODY
|
|
|
|
MORE BODY
|
|
|
|
DIRECTIVE: The directive name
|
|
VALUE: Optional; the value to pass to the directive
|
|
LINK: Optional; a name for internal linking
|
|
EXTENSION: Optional; extended directive functionality
|
|
PARAMETER: Optional; value to pass to extended directive functions
|
|
BODY: Optional; the directive body (certain directives only)
|
|
|
|
|
|
_heading: Flatworm Directives @<flatworm-directive>
|
|
|
|
_definition: **_section:** //TITLE//
|
|
A //section// has its **TITLE** in an H1 font. Sections are linked
|
|
to in //Table of Contents// and have a dividing line drawn above
|
|
them.
|
|
|
|
The body supports markdown.
|
|
|
|
There should only be one ``_section:`` per page.
|
|
|
|
**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@nav](flatworm--ext-nav), [@note](flatworm--ext-note)
|
|
|
|
_definition: **_subsection:** //TITLE//
|
|
A //subsection// has its **TITLE** in an H2 font. Subsections are linked
|
|
to in //Table of Contents// and have a dividing line drawn above
|
|
them.
|
|
|
|
The title and body support markdown.
|
|
|
|
**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)
|
|
|
|
_definition: **_heading:** //TITLE//
|
|
A //heading// has its **TITLE** in an H3 font.
|
|
|
|
The title and body support markdown.
|
|
|
|
**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)
|
|
|
|
_definition: **_definition:** //TERM//
|
|
A //definition// has its **TERM** in normal text and the body is
|
|
indented.
|
|
|
|
The title and body support markdown.
|
|
|
|
_definition: **_property:** //SIGNATURE//
|
|
A //property// has its JavaScript **SIGNATURE** formatted.
|
|
|
|
The body supports markdown and the return portion of the signature
|
|
support markdown links.
|
|
|
|
**Extensions:** [@src](flatworm--ext-src)
|
|
|
|
_definition: **_note:** //BANNER//
|
|
A //note// is placed in a blue bordered-box to draw attention to it.
|
|
|
|
The body supports markdown.
|
|
|
|
_definition: **_warning:** //BANNER//
|
|
A //warning// is placed in an orange bordered-box to draw attention to it.
|
|
|
|
The body supports markdown.
|
|
|
|
_definition: **_code:** //CAPTION//
|
|
Creates a [Code](flatworm--code) block.
|
|
|
|
The body does **not** support markdown, and will be output exactly as
|
|
is, with the exception of [Code Evaluation](flatworm--code-eval).
|
|
|
|
If a line begins with a ``"_"``, it should be escaped with a ``"\\"``.
|
|
|
|
**Extensions:** [@lang](flatworm--ext-lang)
|
|
|
|
_definition: **_table:** //FOOTER//
|
|
|
|
Creates a [Table](flatworm--table) structured according to the body.
|
|
|
|
Each cell contents supports markdown and variables supports markdown.
|
|
|
|
**Extensions:** [@style](flatworm--ext-style)
|
|
|
|
_definition: **_toc:**
|
|
A //toc// injects a Table of Contents, loading each line of the
|
|
body as a filename and recursively loads the //toc// if present,
|
|
otherwise all the //sections// and //subsections//.
|
|
|
|
The body does **not** support markdown, as it is interpreted as
|
|
a list of files and directories to process.
|
|
|
|
_definition: **_null:**
|
|
A //null// is used to terminated a directive. For example, after
|
|
a //definition//, the bodies are indented, so a //null// can be
|
|
used to reset the indentation.
|
|
|
|
The body supports markdown.
|
|
|
|
_code: Example @lang<text>
|
|
|
|
\_section: Hello World @<link-main>
|
|
Body for section...
|
|
|
|
|
|
\_subsection: Some Example @<link-secondary>
|
|
Body for subsection...
|
|
|
|
|
|
\_heading: Large Bold Text @<link-here>
|
|
Body for heading...
|
|
|
|
|
|
\_definition: Flatworm
|
|
A phylum of relatively **simple** bilaterian, unsegmented,
|
|
soft-bodied invertebrates.
|
|
|
|
|
|
\_property: String.fromCharCode(code) => string
|
|
Returns a string created from //code//, a sequence of
|
|
UTF-16 code units.
|
|
|
|
|
|
\_code: heading
|
|
|
|
// Some code goes here
|
|
while(1);
|
|
|
|
|
|
\_table: Table Footer
|
|
|
|
| **Name** | **Color** |
|
|
| Apple | Red |
|
|
| Banana | Yellow |
|
|
| Grape | Purple |
|
|
|
|
|
|
\_toc:
|
|
some-file
|
|
some-directory
|
|
|
|
|
|
\_note: Title
|
|
This is placed in a blue box.
|
|
|
|
|
|
\_warning: Title
|
|
This is placed in an orange box.
|
|
|
|
|
|
\_null:
|
|
This breaks out of a directive. For example, to end
|
|
a ``_note:`` or ``_code:``.
|
|
|
|
|
|
_subsection: Markdown @<flatworm-markdown>
|
|
|
|
The markdown is simple and does not have the flexibility of
|
|
other dialects, but allows for **bold**, //italic//,
|
|
__underlined__, ``monospaced``, super^^script^^ and ~~strike~~
|
|
text, supporting [links](flatworm-markdown) and lists.
|
|
|
|
Lists are rendered as blocks of a body, so cannot be used within
|
|
a title or within another list.
|
|
|
|
_code: @lang<text>
|
|
|
|
**bold text**
|
|
|
|
//italic text//
|
|
|
|
__underlined text__
|
|
|
|
``monospace code``
|
|
|
|
^^superscript text^^
|
|
|
|
~~strikeout text~~
|
|
|
|
- This is a list
|
|
- With bullet points
|
|
- With a total of three items
|
|
|
|
This is a [Link to Ethereum](https://ethereum.org) and this
|
|
is an [Internal Link](some-link).
|
|
|
|
This is a self-titled link [[https://ethereumorg]] and this
|
|
[[some-link]] will use the title from its directives value.
|
|
|
|
|
|
_subsection: Code @<flatworm--code>
|
|
|
|
The code directive creates a monospace, contained block useful
|
|
for displaying code samples.
|
|
|
|
_heading: JavaScript Evaluation @<flatworm--code-eval>
|
|
|
|
For JavaScript files, the file is transpiled and executed in a VM,
|
|
allowiung output (or exceptions) of blocks to be included in the
|
|
fragment output.
|
|
|
|
The entire **code fragment** source is included in an async IIFE,
|
|
whick means ``await`` is allowed, and several special comment
|
|
directives are allowed.
|
|
|
|
A ``/\/_hide:`` will include any following code directly into the
|
|
output, but will not include it in the generated output for the fragment.
|
|
|
|
A ``/\/_log:`` will include the value of any following expression in the
|
|
output, prefixed with a ``/\/ ``. Renderers will mark output in different
|
|
style if possible.
|
|
|
|
A ``/\/_result:`` will begin a block, assigning the contents to ``_``. The
|
|
block can be ended with a ``/\/_log:`` or ``/\/_null:``, if no value is given
|
|
to log, then ``_`` is assumed. If an error occurs, generation fails.
|
|
|
|
A ``/\/_throws:`` will begin a block, which is expected to throw assigning
|
|
the error to ``_``. The block can be ended with a ``/\/_log:`` or ``/\/_null:``,
|
|
if no value is given to log, then ``_`` is assumed. If an error do not occur,
|
|
generation fails.
|
|
|
|
_code: Code Evaluation Example @lang<text>
|
|
|
|
\_code: Result of Code Example @lang<javascript>
|
|
|
|
//_hide: const url = require("url");
|
|
|
|
//_result:
|
|
url.parse("https://www.ricmoo.com/").protocol
|
|
//_log:
|
|
|
|
//_throws:
|
|
url.parse(45)
|
|
//_log:
|
|
|
|
// You want to assign (doesn't emit eval) AND display the value
|
|
const foo = 4 + 5;
|
|
//_log: foo
|
|
|
|
|
|
_code: Result of Code Example @lang<javascript>
|
|
|
|
//_hide: const url = require("url");
|
|
|
|
//_result:
|
|
url.parse("https://www.ricmoo.com/").protocol
|
|
//_log:
|
|
|
|
//_throws:
|
|
url.parse(45)
|
|
//_log:
|
|
|
|
// You want to assign (doesn't emit eval) AND display the value
|
|
const foo = 4 + 5;
|
|
//_log: foo
|
|
|
|
|
|
_heading: Languages
|
|
|
|
The language can be specified using the [@lang extension](flatworm--ext-lang).
|
|
|
|
_table:
|
|
|
|
| **Language** | **Notes** |
|
|
| javascript | Syntax highlights and [evaluates](flatworm--code-eval) the JavaScript |
|
|
| script | Same as ``javascript``, but does not evaluate the results |
|
|
| shell | Shell scripts or command-line |
|
|
| text | Plain text with no syntax highlighting |
|
|
|
|
_subsection: Tables @<flatworm--table>
|
|
|
|
The table directive consumes the entire body up until the next
|
|
directive. To terminate a table early to begin a text block,
|
|
use a **_null:** directive.
|
|
|
|
Each line of the body should be [Row Data](flatworm--table-row) or a
|
|
[Variable Declaration](flatworm--table-variable) (or continuation of
|
|
a //Variable Declaration//). Blank lines are ignored.
|
|
|
|
_heading: Row Data @<flatworm--table-row>
|
|
|
|
Each **Row Data** line must begin and end with a **``"|"``**, with each
|
|
gap representing the cell data, [alignment](flatworm--table-alignment)
|
|
with optional [column and row spanning](flatworm--table-spanning).
|
|
|
|
|
|
_heading: Alignment @<flatworm--table-alignment>
|
|
|
|
The alignment for a cell is determined by the whitespace surrounding the
|
|
cell data.
|
|
|
|
_table: Alignment Conditions (higher precedence listed first)
|
|
|
|
| **Alignment** | **Whitespace** |
|
|
| //Left// | 1 or fewer spaces before the content |
|
|
| //Right// | 1 or fewer spaces after the content |
|
|
| //Center// | 2 or more space **both** before and after the content |
|
|
|
|
|
|
_code: Alignment Example @lang<text>
|
|
|
|
\_table: Result of Alignment Example @style<compact>
|
|
|
|
| center |
|
|
|
|
| left |
|
|
|left |
|
|
|
|
| right |
|
|
| right|
|
|
|
|
_table: Result of Alignment Example @style<compact>
|
|
|
|
| center |
|
|
|
|
| left |
|
|
|left |
|
|
|
|
| right |
|
|
| right|
|
|
|
|
|
|
_heading: Row and Column Spanning @<flatworm--table-spanning>
|
|
|
|
A column may end its content with any number of **``"<"``** which indicates
|
|
how many //additional// columns to extend into.
|
|
|
|
If the cell content contains only a **``"^"``**, then the row above is
|
|
extended into this cell (into the same number of columns).
|
|
|
|
_code: Cell Spanning Example @lang<text>
|
|
|
|
\_table: Result of Cell Spanning Example @style<compact>
|
|
|
|
| (1x1) | (1x2) <| (2x1) |
|
|
| (2x2) <| (2x1) | ^ |
|
|
| ^ | ^ | (1x1) |
|
|
|
|
_table: Result of Cell Spanning Example @style<compact>
|
|
|
|
| (1x1) | (1x2) <| (2x1) |
|
|
| (2x2) <| (2x1) | ^ |
|
|
| ^ | ^ | (1x1) |
|
|
|
|
|
|
_heading: Styles @<flatworm--table-style>
|
|
|
|
The [@style extension](flatworm--ext-style) for a table can be used to control its
|
|
appearance.
|
|
|
|
_table:
|
|
|
|
| **Name** | **Width** | **Columns** |
|
|
| //minimal// | minimum size | best fit |
|
|
| //compact// | 40% | evenly spaced |
|
|
| //wide// | 67% | evenly spaced |
|
|
| //full// | 100% | evenly spaced |
|
|
|
|
|
|
_heading: Variables @<flatworm--table-variable>
|
|
|
|
Often the layout of a table is easier to express and maintain without
|
|
uneven or changing content within it. So the content can be defined
|
|
separately within a table directive using **variables**. A variable
|
|
name must begin with a letter and must only contain letters and numbers.
|
|
|
|
Variables are also useful when content is repeated throughout a table.
|
|
|
|
A variable is declared by starting a line with ``"$NAME:"``, which
|
|
consumes all lines until the next variable declaration or until the
|
|
next table row line.
|
|
|
|
A variable name must start with a letter and may consist of letters and
|
|
numbers. (i.e. ``/[a-z][a-z0-9]*/i``)
|
|
|
|
_code: Variables Example @lang<text>
|
|
|
|
\_table: Result of Variables Example
|
|
|
|
$Yes: This option is supported.
|
|
$No: This option is **not** supported
|
|
$bottom: This just represents an example of
|
|
what is possible. Notice that variable
|
|
content can span multiple lines.
|
|
|
|
| **Feature** | **Supported** |
|
|
| Dancing Monkey | $Yes |
|
|
| Singing Turtle | $No |
|
|
| Newt Hair | $Yes |
|
|
| $bottom <|
|
|
|
|
_table: Result of Variables Example
|
|
|
|
$Yes: This option is supported.
|
|
$No: This option is **not** supported.
|
|
$bottom: This just represents an example of
|
|
what is possible. Notice that variable
|
|
content can span multiple lines.
|
|
|
|
| **Feature** | **Supported** |
|
|
| Dancing Monkey | $Yes |
|
|
| Singing Turtle | $No |
|
|
| Newt Hair | $Yes |
|
|
| $bottom <|
|
|
|
|
|
|
_subsection: Configuration @<flatworm-config>
|
|
|
|
Configuration is optional (but highly recommended) and may be either
|
|
a simple JSON file (config.json) or a JS file (config.js) placed in
|
|
the top of the source folder.
|
|
|
|
TODO: example JSON and example JS
|
|
|
|
|
|
_subsection: Extensions @<flatworm-extensions>
|
|
|
|
_heading: @inherit\< //markdown// > @<flatworm--ext-inherit>
|
|
|
|
Adds an inherits description to a directive. The //markdown// may contain links.
|
|
|
|
|
|
_heading: @lang\< //text// > @<flatworm--ext-lang>
|
|
|
|
Set the language a [code directive](flatworm--code) should be
|
|
syntax-highlighted for. If "javascript", the code will be evaluated.
|
|
|
|
|
|
_heading: @nav\< //text// > @<flatworm--ext-nav>
|
|
|
|
Sets the name in the breadcrumbs when not the current node.
|
|
|
|
|
|
_heading: @note\<// markdown// > @<flatworm--ext-note>
|
|
|
|
Adds a note to a directive. The //markdown// may contain links. If the directive
|
|
already has an @INHERIT extension, that will be used instead and the @NOTE will
|
|
be ignored.
|
|
|
|
|
|
_heading: @src\< //key// > @<flatworm--ext-src>
|
|
|
|
Calls the configuration ``getSourceUrl(key, VALUE)`` to get a URL which
|
|
will be linked to by a link next to the //directive//.
|
|
|
|
This extended directive function requires an advanced ``config.js`` [[flatworm-config]]
|
|
file since it requires a JavaScript function.
|
|
|
|
|
|
_heading: @style\< //text// > @<flatworm--ext-style>
|
|
|
|
The [Table Style](flatworm--table-style) to use for a table directive.
|