gendocs: Library for generating interface documentation from types

[ bsd3, library, web ] [ Propose Tags ]

Please see README.md


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.1, 0.1.2, 0.1.3
Dependencies aeson, aeson-pretty, base (>=4.7 && <5), bytestring, safe, text [details]
License BSD-3-Clause
Copyright Orbital Labs
Author Sean Hess
Maintainer seanhess@gmail.com
Category Web
Home page https://github.com/seanhess/gendocs#readme
Source repo head: git clone https://github.com/seanhess/gendocs
Uploaded by seanhess at 2017-02-27T22:50:01Z
Distributions NixOS:0.1.3
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 2759 total (16 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-02-27 [all 1 reports]

Readme for gendocs-0.1.1

[back to package description]

Generate interface documentation for your types

Example

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
module Example where

import Data.Aeson (ToJSON)
import Data.Proxy (Proxy(..))
import Data.Docs (markdown, Docs(..), Sample(..), genDocs)
import Data.Text (Text)
import qualified Data.Text as Text
import GHC.Generics (Generic)

data Person = Person
    { name :: Text
    , age :: Age
    , hobbies :: [Hobby]
    } deriving (Show, Eq, Generic)
instance ToJSON Person
instance Docs Person
instance Sample Person where
    sample _ = Person
      { name = "Bob"
      , age = sample (Proxy :: Proxy Age)
      , hobbies = [Haskell, Friends]
      }

newtype Age = Age Int
    deriving (Show, Eq, Generic)
instance ToJSON Age
instance Docs Age where
    docs = genDocs "Age in years"
instance Sample Age where
    sample _ = Age 31
    samples _ = [Age 31, Age 24]

data Hobby = Haskell | Friends | Movies
    deriving (Show, Eq, Generic, Enum, Bounded)
instance ToJSON Hobby
instance Docs Hobby
instance Sample Hobby where
    sample _ = Haskell
    allValues _ = [minBound..]

doc :: IO ()
doc = do
    putStrLn $ Text.unpack json

json :: Text
json = Text.intercalate "\n\n\n" $
  [ markdown (Proxy :: Proxy Person)
  , markdown (Proxy :: Proxy Age)
  , markdown (Proxy :: Proxy Hobby)
  ]

This generates the following output

Person
---------------------

| Field   | Type              |
|---------|-------------------|
| name    | [Text](#text)     |
| age     | [Age](#age)       |
| hobbies | [[Hobby]](#hobby) |

```
{
    "age": 31,
    "hobbies": [
        "Haskell",
        "Friends"
    ],
    "name": "Bob"
}
```


Age
---------------------

Age in years

```
31
```


Hobby
---------------------

| Values    |
|-----------|
| "Haskell" |
| "Friends" |
| "Movies"  |

```
"Haskell"
```