-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Generate documentation via TypeRep for Servant API
--   
--   This library uses <a>Data.Typeable</a> to generate documentation for
--   <a>Servant</a> API types. It relies on the <a>typeRep</a> of Servant's
--   combinators and other datatypes used in the API to generate the
--   documentation.
@package servant-docs-simple
@version 0.1.0.0


-- | Renders the intermediate structure into common documentation formats
--   
--   <b>Example scripts</b>
--   
--   <a>Generating plaintext/JSON documentation from api types</a>
--   
--   <a>Writing our own rendering format</a>
--   
--   <b>Example of rendering the intermediate structure</b>
--   
--   <i>Intermediate structure</i>
--   
--   <pre>
--   Endpoints [Node "/hello/world"
--                   (Details [ Node "RequestBody" (Details [ Node "Format"
--                                                                 (Detail "': * () ('[] *)")
--                                                          , Node "ContentType"
--                                                                 (Detail "()")
--                                                          ])
--                            , Node "RequestType" (Detail "'POST")
--                            , Node "Response" (Details [ Node "Format"
--                                                              (Detail "': * () ('[] *)")
--                                                       , Node "ContentType"
--                                                              (Detail "()")
--                                                       ])
--                            ])]
--   </pre>
--   
--   <i>JSON</i>
--   
--   <pre>
--   {
--       "/hello/world": {
--           "Response": {
--               "Format": "': * () ('[] *)",
--               "ContentType": "()"
--           },
--           "RequestType": "'POST",
--           "RequestBody": {
--               "Format": "': * () ('[] *)",
--               "ContentType": "()"
--           }
--       }
--   }
--   </pre>
--   
--   <i>Text</i>
--   
--   <pre>
--   /hello/world:
--   RequestBody:
--       Format: ': * () ('[] *)
--       ContentType: ()
--   RequestType: 'POST
--   Response:
--       Format: ': * () ('[] *)
--       ContentType: ()
--   </pre>
module Servant.Docs.Simple.Render

-- | Value representation; see <a>Endpoints</a> and <a>Node</a>
--   documentation for a clearer picture
data Details

-- | List of Parameter-Value pairs
Details :: [Node] -> Details

-- | Single Value
Detail :: Text -> Details

-- | Intermediate documentation structure, a linked-list of endpoints
--   (<b><a>Node</a>s</b>)
--   
--   API type:
--   
--   <pre>
--   type API = "users" :&gt; (      "update" :&gt; Response '[()] ()
--                           :&lt;|&gt; "get"    :&gt; Response '[()] ()
--                         )
--   </pre>
--   
--   Parsed into Endpoints:
--   
--   <pre>
--   Endpoints [ Node "/users/update"
--                    (Details [ Node "Response"
--                                    (Details [ Node "Format" (Detail "': * () ('[] *)")
--                                             , Node "ContentType" (Detail "()")
--                                             ])
--                             ])
--             , Node "/users/get"
--                    (Details [ Node "Response"
--                                    (Details [ Node "Format" (Detail "': * () ('[] *)")
--                                             , Node "ContentType" (Detail "()")
--                                             ])
--                             ])
--             ]
--   </pre>
--   
--   For a breakdown reference <a>Node</a>
--   
--   For more examples reference <a>Test.Servant.Docs.Simple.Samples</a>
newtype Endpoints
Endpoints :: [Node] -> Endpoints

-- | Key-Value pair for endpoint parameters and their values
--   
--   <b>Example 1</b>
--   
--   An endpoint is represented as a node, with the route as its parameter
--   and its Details as its value
--   
--   <pre>
--   Node "/users/get" &lt;Details&gt;
--   </pre>
--   
--   <b>Example 2</b>
--   
--   Details of each endpoint can also be represented as nodes
--   
--   Given the following:
--   
--   <pre>
--   Response '[()] ()
--   </pre>
--   
--   This can be interpreted as a Response parameter, with a value of 2
--   Details, Format and ContentType
--   
--   In turn, this:
--   
--   <pre>
--   Format: '[()]
--   </pre>
--   
--   can be interpreted as a Format parameter with a value of
--   <tt>'[()]</tt>.
--   
--   And so parsing <tt>Response '[()] ()</tt> comes together as:
--   
--   <pre>
--   Node "Response"                                               --- Parameter
--        (Details [ Node "Format"                   -- Parameter  ---
--                        (Detail "': * () ('[] *)") -- Value         |
--                 , Node "ContentType"              -- Parameter     | Value
--                        (Detail "()")              -- Value         |
--                 ])                                              ---
--   </pre>
data Node
Node :: Text -> Details -> Node

-- | Convert Endpoints into different documentation formats
class Renderable a
render :: Renderable a => Endpoints -> a

-- | Conversion to JSON using Data.Aeson
newtype Json
Json :: Value -> Json
[getJson] :: Json -> Value

-- | Conversion to prettyprint
newtype Pretty ann
Pretty :: Doc ann -> Pretty ann
[getPretty] :: Pretty ann -> Doc ann

-- | Conversion to plaintext
newtype PlainText
PlainText :: Text -> PlainText
[getPlainText] :: PlainText -> Text
instance GHC.Show.Show Servant.Docs.Simple.Render.PlainText
instance GHC.Classes.Eq Servant.Docs.Simple.Render.PlainText
instance GHC.Show.Show Servant.Docs.Simple.Render.Json
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Json
instance GHC.Show.Show Servant.Docs.Simple.Render.Endpoints
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Endpoints
instance GHC.Show.Show Servant.Docs.Simple.Render.Node
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Node
instance GHC.Show.Show Servant.Docs.Simple.Render.Details
instance GHC.Classes.Eq Servant.Docs.Simple.Render.Details
instance Servant.Docs.Simple.Render.Renderable Servant.Docs.Simple.Render.PlainText
instance Servant.Docs.Simple.Render.Renderable (Servant.Docs.Simple.Render.Pretty ann)
instance Servant.Docs.Simple.Render.Renderable Servant.Docs.Simple.Render.Json
instance Data.Aeson.Types.ToJSON.ToJSON Servant.Docs.Simple.Render.Endpoints
instance Data.Aeson.Types.ToJSON.ToJSON Servant.Docs.Simple.Render.Details


-- | Parse Servant API into documentation
--   
--   <b>Example script</b>
--   
--   <a>Generating the intermediate documentation structure</a>
--   
--   <b>Example of parsing an API</b>
--   
--   <i>API type</i>
--   
--   <pre>
--   type API = "hello" :&gt; "world" :&gt; Request :&gt; Response
--   type Request = ReqBody '[()] ()
--   type Response = Post '[()] ()
--   </pre>
--   
--   <i>Intermediate structure</i>
--   
--   <pre>
--   Endpoints [Node "/hello/world"
--                   (Details [ Node "RequestBody" (Details [ Node "Format"
--                                                                 (Detail "': * () ('[] *)")
--                                                          , Node "ContentType"
--                                                                 (Detail "()")
--                                                          ])
--                            , Node "RequestType" (Detail "'POST")
--                            , Node "Response" (Details [ Node "Format"
--                                                              (Detail "': * () ('[] *)")
--                                                       , Node "ContentType"
--                                                              (Detail "()")
--                                                       ])
--                            ])]
--   </pre>
module Servant.Docs.Simple.Parse

-- | Flattens API into type level list of <a>Endpoints</a>
class HasParsable api
parse :: HasParsable api => Endpoints
instance forall a (api :: a) (b :: [a]). (Servant.Docs.Simple.Parse.HasDocumentApi api, Servant.Docs.Simple.Parse.HasCollatable b) => Servant.Docs.Simple.Parse.HasCollatable (api : b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol route) => Servant.Docs.Simple.Parse.HasDocumentApi (route Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol dRoute, Data.Typeable.Internal.Typeable t) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Capture.Capture' m dRoute t Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol dRoute, Data.Typeable.Internal.Typeable t) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Capture.CaptureAll dRoute t Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Network.HTTP.Types.Version.HttpVersion Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.IsSecure.IsSecure Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.RemoteHost.RemoteHost Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol desc) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Description.Description desc Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol s) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Description.Summary s Servant.API.Sub.:> b)
instance Servant.Docs.Simple.Parse.HasDocumentApi b => Servant.Docs.Simple.Parse.HasDocumentApi (Data.Vault.Lazy.Vault Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol realm, Data.Typeable.Internal.Typeable a) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.BasicAuth.BasicAuth realm a Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol token) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Experimental.Auth.AuthProtect token Servant.API.Sub.:> b)
instance forall k b (ct :: GHC.Types.Symbol) (typ :: k) (m :: [*]). (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Header.Header' m ct typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol param) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.QueryParam.QueryFlag param Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol param, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.QueryParam.QueryParam' m param typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, GHC.TypeLits.KnownSymbol param, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.QueryParam.QueryParams param typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.ReqBody.ReqBody' m ct typ Servant.API.Sub.:> b)
instance (Servant.Docs.Simple.Parse.HasDocumentApi b, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Stream.StreamBody' m ct typ Servant.API.Sub.:> b)
instance forall k1 (m :: k1) (ct :: [*]) typ (s :: GHC.Types.Nat). (Data.Typeable.Internal.Typeable m, Data.Typeable.Internal.Typeable ct, Data.Typeable.Internal.Typeable typ) => Servant.Docs.Simple.Parse.HasDocumentApi (Servant.API.Verbs.Verb m s ct typ)
instance Servant.Docs.Simple.Parse.HasCollatable (Servant.API.TypeLevel.Endpoints a) => Servant.Docs.Simple.Parse.HasParsable a
instance Servant.Docs.Simple.Parse.HasParsable Servant.API.Empty.EmptyAPI
instance Servant.Docs.Simple.Parse.HasCollatable '[]


-- | Parse and render an API type, write documentation to file, stdout
--   
--   <b>Example script</b>
--   
--   <a>Writing documentation to file</a>
--   
--   <b>Using this script</b>
--   
--   <i>With the following language extensions</i>
--   
--   <pre>
--   DataKinds
--   TypeApplications
--   TypeOperators
--   </pre>
--   
--   <pre>
--   module Main where
--   
--   import Data.Aeson (Value)
--   import Data.Text (Text)
--   
--   import Servant.API ((:&gt;), Post, ReqBody)
--   import Servant.Docs.Simple (document, documentWith, stdoutJson, stdoutPlainText, writeDocsJson,
--                               writeDocsPlainText)
--   import Servant.Docs.Simple.Render (Json (..), PlainText (..))
--   
--   -- Our API type
--   type API = "hello" :&gt; "world" :&gt; Request :&gt; Response
--   type Request = ReqBody '[()] ()
--   type Response = Post '[()] ()
--   
--   main :: IO ()
--   main = do
--     -- Writes to the file $PWD/docsJson
--     writeDocsJson @API "docs.json"
--   
--     -- Writes to the file $PWD/docsPlainText
--     writeDocsPlainText @API "docs.txt"
--   </pre>
--   
--   <b>Expected Output</b>
--   
--   <i>Files should be generated relative to <tt>$PWD</tt></i>
--   
--   <pre>
--   $ ls | grep docs
--   docs.json
--   docs.txt
--   </pre>
--   
--   <i>docs.json</i>
--   
--   <pre>
--   {
--       "/hello/world": {
--           "Response": {
--               "Format": "': * () ('[] *)",
--               "ContentType": "()"
--           },
--           "RequestType": "'POST",
--           "RequestBody": {
--               "Format": "': * () ('[] *)",
--               "ContentType": "()"
--           }
--       }
--   }
--   </pre>
--   
--   <i>docs.txt</i>
--   
--   <pre>
--   /hello/world:
--   RequestBody:
--       Format: ': * () ('[] *)
--       ContentType: ()
--   RequestType: 'POST
--   Response:
--       Format: ': * () ('[] *)
--       ContentType: ()
--   </pre>
module Servant.Docs.Simple

-- | Convert API type into PlainText format
document :: forall api. HasParsable api => PlainText

-- | Convert API type into specified formats
documentWith :: forall api a. (HasParsable api, Renderable a) => a

-- | Write documentation as JSON to stdout
stdoutJson :: forall api. HasParsable api => IO ()

-- | Write documentation as PlainText to stdout
stdoutPlainText :: forall api. HasParsable api => IO ()

-- | Write documentation as JSON to file
writeDocsJson :: forall api. HasParsable api => FilePath -> IO ()

-- | Write documentation as PlainText to file
writeDocsPlainText :: forall api. HasParsable api => FilePath -> IO ()