# Eloquent
[![Build Status](https://travis-ci.org/rekki/eloquent.svg?branch=master)](https://travis-ci.org/rekki/eloquent)
Generates markdown documentation for non-standard use cases.
Eloquent is used to generate markdown documentation for situations where using `@moduledoc` and `@doc` are not good enough. For example websocket channels or API endpoints.
## Installation
This package is [available in Hex](https://hex.pm/packages/eloquent). Add it to your dependencies to install.
```elixir
def deps do
[
{:eloquent, "~> 0.2.0"}
]
end
```
## Usage
Once included as a dependency, `use` Eloquent in the desired module:
```elixir
use Eloquent,
prefix: "http-api-v1",
destination_folder: "priv/docs",
validator: HttpRequestValidator
```
| Option | Description |
|--------------------|-----------------------------------------------------------|
| prefix | What to prefix the markdown files with |
| destination_folder | Where to out the markdown files |
| validator | A validator to validate any requests in the documentation |
You will then have two things available in the module `@collection_doc` is used to write documentation for the module as a whole.
The function `doc_resource/1` is where the bulk of the documentation will be. In it you will define the name, description and examples of a resource, here is an example:
```elixir
doc_resource name: "new-user",
description: """
Create a new user
""",
example: %{
request: """
{
"name": "Claude"
}
""",
response: """
{
"status": "ok",
"user": {
"id": 12,
"name": "Claude"
}
}
"""
}
```
On compilation Eloquent will generate markdown files based on this documentation and produce something similar to [one of our test fixtures](test/fixtures/doc/expected/http-api-v1-http-resource.md).