Manual: doctools

Describes how the documentation tools work in Lever. Not complete or comprehensive description.

Lever's documentation tools supports an upwards workflow where the documentation follows the source code. This helps to ensure that the documentation is indeed accurate documentation and not merely good wishes.

Comprehensive and good documentation is a very different thing than the source code, therefore the source code and documentation remain in different files. The documentation is contained in the 'doc' -directory that is copied along into the runtime distribution.

The documentation is accessible to runtime, although the tools to retrieve and read documentation in REPL do not currently exist.

Documentation is written in texopic -language. The language is remotely similar with XML or HTML but has an exception that it differentiates between vertical and horizontal elements in the text. The details about the language will appear in the texopic module docs.

A single documentation file functions as both a manual and a reference. It is usable as both with searching, indexing and filtering tools.

The appropriate reference cards are pointed out by groups within the text. The cards contain lot of information that is treated appropriately.

The description of all fields is not completed.

macros : dict
JSON-compatible structure that contains a listing about all the Texopic segments and groups recognized by doctools.

Is not containing the recognized macros. This is useful in combination with the texopic.read_file.

volatile

Since Lever is a very amenable language for change it is important to communicate when things may change. Sometimes it may even require that we know how and why things change. For this reason we have a 'status/0' group separator that is present in all reference card groups.

If the status field is missing, it means that the details of the object described in the reference are highly stable. The changes of such function are only allowed after a major version change. Changes into such details may require a transition time to be scheduled.

The documentation generator automatically adds #status volatile into every reference card. This means that the author reserves the option to change the interface and that only the exact version or even an exact git commit is required for the program that uses this function.

Volatile status is meant for the situation where the status of a specific interface is not determined. Another status, internal, can be used to point out that the documented item is an internal implementation detail not meant for external use. Relying on such features require same measurements as if the status was 'volatile'.

get_block(members, ref)
members not documented
ref not documented
returns not documented
not documented
volatile
get_module_index(module, block = null)
module not documented
block not documented
returns not documented
not documented
volatile
get_scope_index(scope, recursive = null)
scope not documented
recursive not documented
returns not documented
not documented
volatile
import : Import
not documented
volatile
import_all_modules(scope)
scope not documented
returns not documented
not documented
volatile
is_function(val)
val not documented
returns not documented
not documented
volatile
macros : dict
not documented
volatile
name = "doctools"
not documented
volatile
scan(members, this, link, base)
members not documented
this not documented
link not documented
base not documented
returns not documented
not documented
volatile
scan_function(block, func)
block not documented
func not documented
returns not documented
not documented
volatile
try_getattr(obj, name, default = null)
obj not documented
name not documented
default not documented
returns not documented
not documented
volatile