servant-pandoc: Use Pandoc to render servant API documentation

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Use pandoc to generate documentation for your Servant API.


[Skip to Readme]

Properties

Versions 0.1, 0.1.0.1, 0.1.0.2, 0.4.0, 0.4.1, 0.4.1.1, 0.4.1.2, 0.4.1.3, 0.4.1.4, 0.5.0.0, 0.5.0.0
Change log CHANGELOG
Dependencies base (>=4.7 && <5), bytestring (>=0.10 && <0.11), case-insensitive (>=0.2 && <1.3), http-media (>=0.6 && <0.8), lens (>=4.9 && <5), pandoc-types (>=1.12 && <1.18), semigroups (>=0.17 && <0.19), servant-docs (>=0.11.1 && <0.12), string-conversions (>=0.1 && <0.5), text (>=1.2 && <1.3), unordered-containers (>=0.2 && <0.3) [details]
License MIT
Author Matthew Pickering, Ivan Miljenovic
Maintainer Ivan.Miljenovic@gmail.com
Category Web, Servant
Source repo head: git clone https://github.com/mpickering/servant-pandoc/
Uploaded by IvanMiljenovic at 2018-01-16T23:25:43Z

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for servant-pandoc-0.5.0.0

[back to package description]

Hackage Build Status

An extension to servant-docs that allows you to use Pandoc to render your Servant API documentation.

How to use this package

Generate documentation directly

A very simple program to render the API documentation as a mediawiki document might look as follows.

import Text.Pandoc
import Servant.Docs.Pandoc
import Servant.Docs
import Data.Default (def)

myApi :: Proxy MyAPI myApi = Proxy

writeDocs :: API -> IO ()
writeDocs api = writeFile "api.mw" (writeMediaWiki def (pandoc api))

Create a Pandoc filter

The makeFilter function allows you 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:

-- api.hs
main :: IO ()
main = makeFilter (docs myApi)

Then to run this:

pandoc -o api.pdf --filter=api.hs manual.md

Custom filters

A more sophisticated filter might be to actually convert introduction and note bodies to Markdown before processing (note: this is not enabled by default as the pandoc library is GPL-licensed, whereas this library uses pandoc-types which is BSD3-licensed):

import Data.Monoid         (mconcat, (<>))
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 -> Pandoc
    append = (<> mconcat (walkM parseMarkdown (pandoc myApi)))

parseMarkdown :: Block -> [Block]
parseMarkdown bl = case bl of
                     Para  [Str str] -> toMarkdown str
                     Plain [Str str] -> toMarkdown str
                     _               -> [bl]
  where
    toMarkdown = either (const [bl]) unPandoc . readMarkdown def

    unPandoc (Pandoc _ bls) = bls