servant-pandoc: Use Pandoc to render servant API documentation

[ library, mit, servant, web ] [ Propose Tags ]

Use pandoc to generate documentation for your Servant API.


[Skip to Readme]

Modules

[Index]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 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
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:27:39Z
Distributions
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 6948 total (45 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-01-16 [all 1 reports]

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