Package Documentation

All the documentation is written in “package-docs” using fomatted text files, the so-called fDL files. There are two types of fDL file formats: “package” and “command”.

fDL package

There should exist only one file “package.fDL” in the folder “package-docs” and must follow the format:

uDoc/package

__:NAME:__
{package_name}/{package_version}

__:TITLE:__
{text}

__:STATE:__
[ production | under development | under testing ]

__:ABOUT:__
{text}

__:ONLINE:__
{text}

__:NAMESPACES:__
{text}

__:FOLDERS:__
  sDLroot/
  |-- packageroot/     -- package root folder
  |-- |-- data/        -- input/output data folder
  |-- sDL-jobs/        -- output logs of last runs

__:EXAMPLES:__
{text}

__:OTHERINFO:__
{text}

__:PEOPLE:__
{text}

__:HOWTOCITE:__
{text} Please reference the paper [1]_

__:REFERENCES:__
.. [1] {text}

__:CHANGES:__
(appends the content of the file "changes.txt")

The mandatory tags are: NAME, TITLE, STATE, ABOUT, FOLDERS. Other tags are optional. The ONLINE tag is only used when there is a live version of the package that can be used by any anonymous user.

fDL command

Each package command shoud have a command fDL file, describing how it works. The fDL command file should be associated to a namespace. Namespaces are subfolder in “package-docs”, so by default should exists the subfolder “core”, since by default any command should belong to the “core” namespace. A fDL command file has the format:

uDoc/command

__:NAME:__
{command_name}

__:PACKAGE:__
{package_name}/{package_version}

__:NAMESPACE:__
core

__:DESCRIPTION:__
{text}

__:SHORTDESC:__
{text}

__:USAGE:__
{text}

__:OPT_CMD:__
{text}

__:OPT_DESC:__
{text}

__:EXAMPLES:__
{text}

__:OTHERINFO:__
{text}

__:CHANGES:__
(appends the content of the file "changes.txt")

The mandatory tags are: NAME, PACKAGE, NAMESPACE, DESCRIPTION, USAGE. Other tags are optional.

Publishing

To generate and upload the documentation online, in the rootdir of the package, just run:

sDL package