README.md

# 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).