The Makedocs tool converts Monkey documentation to html.
All documentation may use markdown formatting.
General documentation files should have a '.monkeydoc' extension, and should be placed in the docs/monkeydoc directory.
Documentation pages may be linked to using the relative filepath as a link target. For example, if you have added a Tools/MakeImages.monkeydoc file, any file in the Tools directory can link to it using [[MakeImages]].
Files outside the Tools directory can also link to MakeTools using using [[Tools/MakeImages]]. The link text will have the directory stripped so will appear simply as 'MakeImages'.
A plain [[MakeImages]] is also likely to work even outside the Tools directory, as the link resolver will eventually find MakeTools in the main Index, but it may clash with other definitions of MakeImages so a fully qualified link is preferred.
There are two ways to document a module - either by placing documentation 'in source' within the actual module source code by way of 'monkeydoc comments', or in a separate monkeydoc file.
To document a module declaration, you should precede the declaration with a monkeydoc comment. A monkeydoc comment is a block comment starting with the line
Documentation for MyFunction goes here.
In addition, the first monkeydoc comment in the file must be of the form...
#Rem monkeydoc Module my.module
Documentation for my.module goes here...
...where my.module is the full module path of your module.
You may also document a module using an external monkeydoc file. This file should either be in the same directory as the module monkey source file, or in a monkeydoc subdirectory, and must have the same name as the module source file but with a '.monkeydoc' extension instead of '.monkey'.
For example, given the module source file:
The corresponding monkeydoc file may be located either here...
Declarations in a monkeydoc file are normal monkey declarations, but must be preceded by a '# '. Declarations must appear BEFORE the actual documentation.
In addition, a monkeydoc file must start with a '# Module my.module' declaration.
Links to declarations may be created simply by specifying the declaration identifier. The link resolver will attempt to find the correct declaration given the scope of the source documentation.
Links to declarations may also be absolute, in which case a full declaration path should be provided. For example, [[mojo.graphics]] will link to the mojo.graphics module. Absolute links to non-scope declarations should use #identifier to specify the 'leaf' declaration, for example [[mojo.graphics#DrawImage]] will link to the DrawImage function in the mojo.graphics module.
Links may also be created to general documentation, using the same rules as given in the above section 'Markdown links in general documentation'.
You may add examples using an 'Example:' section, eg:
Frobozz the whirligig
Print Frobozz( "Yes!" )
In addition, you can add example programs in monkey source code form to an 'examples' directory located in the same directory as the .monkey or .monkeydoc file the docs are located in.
Such example programs should have the same name as the declaration they are providing an example for, with an '_example' suffix. For example, example code for the above function would be named 'Frobozz_example.monkey'.
Documentation may also in include a links section, eg:
Links: [[X]], [[Y]], [[Z]]
Links will be emitted in a 'links' or 'see also' section.