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


-- | Use Pandoc to render servant API documentation
--   
--   Use pandoc to generate documentation for your Servant API.
@package servant-pandoc
@version 0.5.0.0


-- | There are two ways in which to use this module.
--   
--   The first is to use the renderer directly with the pandoc API. A very
--   simple program to render the API documentation as a mediawiki document
--   might look as follows.
--   
--   <pre>
--   import Text.Pandoc
--   import Servant.Docs.Pandoc
--   import Servant.Docs
--   import Data.Default (def)
--   
--   myApi :: Proxy MyAPI
--   myApi = Proxy
--   
--   writeDocs :: API -&gt; IO ()
--   writeDocs api = writeFile "api.mw" (writeMediaWiki def (pandoc api))
--   </pre>
--   
--   The second approach is to use <a>makeFilter</a> to make a filter which
--   can be used directly with pandoc from the command line. This filter
--   will just append the API documentation to the end of the document.
--   Example usage
--   
--   <pre>
--   -- api.hs
--   main :: IO ()
--   main = makeFilter (docs myApi)
--   </pre>
--   
--   <pre>
--   &gt; pandoc -o api.pdf --filter=api.hs manual.md
--   </pre>
--   
--   A more sophisticated filter can be used to actually convert
--   introduction and note bodies into Markdown for pandoc to be able to
--   process:
--   
--   <pre>
--   import Data.Monoid         (mconcat, (&lt;&gt;))
--   import Servant.Docs.Pandoc (pandoc)
--   import Text.Pandoc         (readMarkdown)
--   import Text.Pandoc.JSON    (Block(Para, Plain), Inline(Str), Pandoc(Pandoc),
--                               toJSONFilter)
--   import Text.Pandoc.Options (def)
--   import Text.Pandoc.Walk    (walkM)
--   
--   main :: IO ()
--   main = toJSONFilter append
--     where
--       append :: Pandoc -&gt; Pandoc
--       append = (&lt;&gt; mconcat (walkM parseMarkdown (pandoc myApi)))
--   
--   parseMarkdown :: Block -&gt; [Block]
--   parseMarkdown bl = case bl of
--                        Para  [Str str] -&gt; toMarkdown str
--                        Plain [Str str] -&gt; toMarkdown str
--                        _               -&gt; [bl]
--     where
--       toMarkdown = either (const [bl]) unPandoc . readMarkdown def
--   
--       unPandoc (Pandoc _ bls) = bls
--   </pre>
module Servant.Docs.Pandoc

-- | Generate a <a>Pandoc</a> representation of a given <a>API</a>.
--   
--   This is equivalent to <tt><a>pandocWith</a>
--   <a>defRenderingOptions</a></tt>.
pandoc :: API -> Pandoc

-- | Generate a <a>Pandoc</a> representation of a given API using the
--   specified options.
--   
--   These options allow you to customise aspects such as:
--   
--   <ul>
--   <li>Choose how many content-types for each request body example are
--   shown with <a>requestExamples</a>.</li>
--   <li>Choose how many content-types for each response body example are
--   shown with <a>responseExamples</a>.</li>
--   <li>Whether all <a>notes</a> should be grouped together under a common
--   heading with <a>notesHeading</a>.</li>
--   </ul>
--   
--   For example, to only show the first content-type of each example:
--   
--   <pre>
--   markdownWith (<a>defRenderingOptions</a>
--                   &amp; <a>requestExamples</a>  <tt>.~</tt> <a>FirstContentType</a>
--                   &amp; <a>responseExamples</a> <tt>.~</tt> <a>FirstContentType</a> )
--                myAPI
--   </pre>
pandocWith :: RenderingOptions -> API -> Pandoc

-- | Helper function which can be used to make a pandoc filter which
--   appends the generate docs to the end of the document.
--   
--   This function is exposed for convenience. More experienced authors can
--   of course define a more complicated filter to inject the API
--   documentation.
makeFilter :: API -> IO ()
