# MDoc

## Overview

A documentation engine for Lua

MDoc was built after frustrations with
[LDoc](https://stevedonovan.github.io/ldoc/manual/doc.md.html),
the usual and most popular documentation engine for lua. Like LDoc, MDoc uses
comments in the source code to generate html files for documentation. Unlike
LDoc, it makes no attempts to be backwards compatible with LuaDoc. This results
in a documentation engine that is free from constraints like "One class per
file" or "one module per file", and allows for an architecture that is more
consistent and elegent overall. MDoc is still in it's early stages, expect
frequent code churn in the near future.

MDoc is used to document my homebrew game engine and VR platform, [Brok\[en\]gine](https://cogarr.net/source/cgit.cgi/brokengine/),
and you can see an example of mdoc in action at the [Brok\[en\]gine reference](https://cogarr.net/brokengine/).

## Installation

The easiest way to download MDoc is with [luarocks](https://github.com/luarocks/luarocks)

```
luarocks install --server=http://rocks.cogarr.net mdoc
```

## Usage

`mdoc` or `mdoc --help` prints help information:

```
mdoc -p <folder> [-p <folder> ...][ -o <folder>][ -t "title"][ -i <file>][ -d <folder>[ -d <folder> ...]][ -m <executable>][ -h]

	-p | --path <folder>                        : Path to search for source files
	-o | --output <folder> = "."                : Folder to output HTML files to (and a cache folder)
	-t | --title "name" = "Mdoc Generated Page" : Title for the html files
	-i | --index <file>                         : File to use for the index file
	-d | --document <folder>                    : Path to search for files to put inder the References section
	-m | --markup-parser <executable>           : Executable to use to parse the descriptions and refrence documents.
	                                              Executable should accept a file path as it's argument, and generate html as it's output.
	-h | --help                                 : print this help
	-v | --verbose                              : print extra information during run
	-c | --no-cache                             : rebuild files, even if they're not out of date.
```

## Bugs

Please report bugs or mail patches to [alex@cogarr.net](mailto://alex@cogarr.net)

You can find instructions for creating patches [here](https://cogarr.net/source/cgit.cgi/?p=about)