Makedocs

Инструмент Makedocs преобразует документацию Monkey в HTML.

Для написания документации вы можете использовать язык разметки markdown.

Общая документация

Общие файлы документации должны иметь расширение ".monkeydoc" и находится в директории docs/monkeydoc.

Ссылки в общей документации

Страницы документации могут использовать относительный путь к файлу в качестве ссылки. Например, если вы добавили файл Tools/MakeImages.monkeydoc, любой файл в директории Tools может ссылаться на него с помощью [[MakeImages]].

Файлы вне директории Tools могут также быть связаны с MakeTools с помощью [[Tools/MakeImages]]. Названия директорий удаляются из отображаемого текста ссылки, поэтому ссылка будет после обработки будет отображаться как "MakeImages".

[[MakeImages]] без указания директории, с большой вероятностью, также сработает даже вне директории Tools, поскольку распознаватель ссылок в конечном итоге найдет MakeTools в главном регистре. Но он может конфликтовать с другими определениями MakeImages, поэтому полная ссылка является предпочтительным вариантом.

Документация модуля

Есть два способа документирования модуля - либо путем размещения документации в файле исходного кода модуля, путем вставки специальных комментариев monkeydoc, или в отдельном файле monkeydoc.

Документирование модулей в исходном коде Monkey

Для документирования модуля, вы должны предшествовать начало документации комментарием monkeydoc. Комментарий monkeydoc представляет собой блочный комментарий, начинающийся со строки #Rem monkeydoc.

Например:

#Rem monkeydoc
Здесь идет документация MyFunction
#End
Function MyFunction:Void() 
...etc... 

Кроме того, первый monkeydoc-комментарий в файле должен иметь вид...

#Rem monkeydoc Module my.module
Здесь идет документация my.module...
#End

...где my.module является полным модульным путем вашего модуля...

Документирование модулей, используя внешний файл monkeydoc

Вы также можете задокументировать модуль с помощью внешнего файла monkeydoc. Этот файл должен быть либо в той же директории, что и исходный файл модуля Monkey, либо в подкаталоге monkeydoc, с тем же названием, что и исходный файл модуля, но с расширением ".monkeydoc" вместо ".monkey".

Например, дан исходный файл модуля:

modules/flixel/flixel.monkey

Соответствующей файл monkeydoc может быть расположен либо здесь...

modules/flixel/flixel.monkeydoc

...либо здесь...

modules/flixel/monkeydoc/flixel.monkeydoc

Объявления в файле monkeydoc являются обычными объявлениями Monkey, но должны начинаться с "#". Объявления должны стоять перед фактической документацией.

Кроме того, файл monkeydoc должен начинаться с объявления "# Module my.module".

Например:

Module my.module 
 
Import brl.stream 
Import brl.markdown 
 
Здесь идет документация my.module 
 
Function MyFunction:Void() 
 
Здесь идет документация MyFunction. 

Ссылки в документации модуля

Ссылки на объявления могут быть созданы простым указанием идентификатора объявления. Распознаватель ссылок будет пытаться найти правильное объявление, с учетом области видимости исходного кода документации.

Ссылки на объявления также могут быть абсолютными. В этом случае, должен быть указан полный путь объявления. Например, [[mojo.graphics]] будет ссылаться на модуль mojo.graphics. Абсолютные ссылки на объявления вне области видимости должны использовать идентификатор "#", чтобы указать прямую ссылку на объявление. Например [[mojo.graphics#DrawImage]] будет ссылаться на функцию DrawImage в модуле mojo.graphics.

По тем же правилам, можно создать ссылки на файлы общей документации.

Добавление примеров в документацию модуля

Пример добавляется через секцию "Example:", например:

#Rem monkeydoc

Frobozz the whirligig

Example:
<pre>
Function Main()
Print Frobozz( "Yes!" )
End
</pre >
#End
Function Frobozz:Voidstr:String ) 
'...etc...

Кроме того, вы можете добавить примеры программ в виде исходного кода Monkey в директорию "examples", которая расположена в той же директории, что и файл .monkey или файл .monkeydoc.

Такие примеры программ должны называться также, как и объявления, для которых они предназначены, с суффиксом "_example". Например, файл с примером использования функции описанной выше называется "Frobozz_example.monkey".

Добавление ссылок в документацию модуля

Документация может также включать в себя список ссылок, например:

Links: [[X]], [[Y]], [[Z]]

Ссылки будут выделены в разделе "ссылки" или "см. также".