212 lines
5.6 KiB
Plaintext
212 lines
5.6 KiB
Plaintext
_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](link-rtd) and
|
|
the [Sphinx](link-sphinx) 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: @lang<text>
|
|
|
|
\_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER>
|
|
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. If an option is specified, it is avaialble as a name for
|
|
intern linking. There should only be one ``_section:`` per page.
|
|
|
|
**Extensions:** @INHERIT, @SRC, @NAV, @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. If an option is specified, it is avaialble as a name for
|
|
internal linking.
|
|
|
|
**Extensions:** @INHERIT, @SRC, @NOTE
|
|
|
|
_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.
|
|
|
|
**Extensions:** @INHERIT, @SRC, @NOTE
|
|
|
|
_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.
|
|
|
|
**Extensions:** @SRC
|
|
|
|
_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:** //TITLE//
|
|
A //code// creates a code block.
|
|
|
|
**Extensions:** @LANG
|
|
|
|
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: @lang<text>
|
|
|
|
\_section: Hello World @<link-to-this-section>
|
|
|
|
\_subsection: Some Example @<link-to-this-subsection>
|
|
|
|
\_heading: Large Bold Text @<link-to-this-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);
|
|
|
|
\_toc:
|
|
some-file
|
|
some-directory
|
|
|
|
\_definition and reset the indentation.
|
|
|
|
\_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
|
|
|
|
|
|
_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.
|
|
|
|
_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: 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>
|
|
|
|
Adds an inherits description to a directive. The //markdown// may contain links.
|
|
|
|
|
|
_heading: @LANG\<text>
|
|
|
|
Set the language the code should be syntax-highlighted for. If "javascript", the
|
|
code will be evaluated.
|
|
|
|
- javascript (will be evaluated)
|
|
- script (useful for JavaScript but that should not be evaluated)
|
|
- shell
|
|
- text
|
|
|
|
|
|
_heading: @NAV\<text>
|
|
|
|
Sets the name in the breadcrumbs when not the current node.
|
|
|
|
|
|
_heading: @NOTE\<markdown>
|
|
|
|
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\<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.
|