ethers.js/docs.wrm/documentation/index.wrm

_title: Flatworm Docs

_section: Flatworm Docs

The //Flatworm Docs// rendering script 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](https://github.com/readthedocs/sphinx_rtd_theme) and
the [Sphinx](https://www.sphinx-doc.org/) project.


_subsection: Fragments @<flatworm-fragments>

Flatworm Docs are made up of fragments. A fragment is either a lone
body of [markdown](flatworm-markdown) text, or a
[directive](flatworm-directive) for specialized formatting, which may
itself have body.


_heading: Directive Format

_code: fragment.txt


_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. If an option is specified, it is avaialble as a name for
intern linking. There should only be one ``_section:`` per page.

_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. If an option is specified, it is avaialble as a name for
internal linking.

_definition: **_heading:** //TITLE//
A //heading// has its **TITLE** in an H3 font. If an option is specified,
it is available as a name for internal linking.

_definition: **_definition:** //TERM//
A //definition// has its **TERM** bolded and the markdown body is
indented.

_definition: **_property:** //SIGNATURE//
A //property// has its JavaScript **SIGNATURE** formatted and the
markdown body is indented.

_definition: **_note:** //TITLE//
A //note// is placed in a blue bordered-box to draw attention to it.

_definition: **_warning:** //TITLE//
A //warning// is placed in an orange bordered-box to draw attention to it.

_definition: **_code:** //FILENAME//
A //code// reads the **FILENAME** and depending on the extension
adjusts it.

For JavaScript files, the file is executed, with ``\/\/!`` replaced
with the result of the last statement and ``\/\/!error`` is replaced
with the throw error. If the error state does not agree, rendering
fails.

_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//.

_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.


_heading: Examples

_code: examples.txt

_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-scripted^^ text,
supporting [links](flatworm-markdown) and lists.

_code: markdown.txt


_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: Extended Directive Functions @<flatworm-extended-directive-functions>

_heading: @INHERIT\<markdown>

Adds an inherits description to a directive. The //markdown// may contain links.

This extended directive function is available for:

- _section
- _subsetion
- _heading

_heading: @SRC\<text>

Calls the configuration ``getSourceUrl(text, 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.

This extended directive function is available for:

- _section
- _subsetion
- _heading
- _property