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. Add it to your dependencies to install.

def deps do
  [
    {:eloquent, "~> 0.2.0"}
  ]
end

Usage

Once included as a dependency, use Eloquent in the desired module:

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:

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.