86 lines
2.6 KiB
Plaintext
86 lines
2.6 KiB
Plaintext
_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 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: **_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
|
|
|