servant-pandoc 0.4.1.3 → 0.4.1.4
raw patch · 4 files changed
+126/−82 lines, 4 filesdep +case-insensitivedep +string-conversionsdep ~servant-docsPVP ok
version bump matches the API change (PVP)
Dependencies added: case-insensitive, string-conversions
Dependency ranges changed: servant-docs
API changes (from Hackage documentation)
Files
- CHANGELOG +38/−0
- README.md +27/−0
- servant-pandoc.cabal +9/−48
- src/Servant/Docs/Pandoc.hs +52/−34
+ CHANGELOG view
@@ -0,0 +1,38 @@+- 0.4.1.4++Supports servant-docs 0.11. Changed behaviour means that this release+can no longer support older versions.++New maintainer: Ivan Miljenovic++- 0.4.1.3++Updated dependencies for http-media, pandoc-types and servant-docs.++- 0.4.1.2++Explicit import list for lens to hopefully avoid dependency problems.++- 0.4.1.1++Modify version bounds++- 0.4.1++Put end points in canonical order.++- 0.4++Update for servant 0.4++- 0.1.0.2++Fix breaking interface change from servant-docs 0.3++- 0.1.0.1++Fix trailing "," when rendering list of values++- 0.1++* Initial release
+ README.md view
@@ -0,0 +1,27 @@+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.++```+ 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))+```++The second approach is to use `makeFilter` 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)++> pandoc -o api.pdf --filter=api.hs manual.md+````
servant-pandoc.cabal view
@@ -1,79 +1,40 @@--- Initial servant-pandoc.cabal generated by cabal init. For further--- documentation, see http://haskell.org/cabal/users-guide/---- The name of the package. name: servant-pandoc---- The package version. See the Haskell package versioning policy (PVP)--- for standards guiding when and how versions should be incremented.--- http://www.haskell.org/haskellwiki/Package_versioning_policy--- PVP summary: +-+------- breaking API changes--- | | +----- non-breaking API additions--- | | | +--- code changes with no API change-version: 0.4.1.3---- A short (one-line) description of the package.+version: 0.4.1.4 synopsis: Use Pandoc to render servant API documentation---- A longer description of the package.-description: See <https://github.com/mpickering/servant-pandoc/blob/master/README.md README>.---- The license under which the package is released.+description: Use pandoc to generate documentation for your Servant API. license: MIT---- The file containing the license text. license-file: LICENSE---- The package author(s).-author: Matthew Pickering---- An email address to which users can send suggestions, bug reports, and--- patches.-maintainer: matthewtpickering@gmail.com---- A copyright notice.--- copyright:-+author: Matthew Pickering, Ivan Miljenovic+maintainer: Ivan.Miljenovic@gmail.com category: Web- build-type: Simple---- Extra files to be distributed with the package, such as examples or a--- README.--- extra-source-files:+extra-source-files: CHANGELOG, README.md --- Constraint on the version of Cabal needed to build this package. cabal-version: >=1.10 -tested-with: GHC == 7.8.2, GHC == 7.10.3+tested-with: GHC == 7.8.2, GHC == 7.10.3, GHC == 8.0.2, GHC == 8.2.1, GHC == 8.3.* source-repository head type: git location: https://github.com/mpickering/servant-pandoc/ library- -- Modules exported by the library. exposed-modules: Servant.Docs.Pandoc - -- Modules included in this library but not exported.- -- other-modules:-- -- LANGUAGE extensions used by modules in this package. other-extensions: OverloadedStrings - -- Other library packages from which modules are imported. build-depends: base >=4.7 && <5 , http-media >=0.6 && <0.8 , lens >=4.9 && <5 , pandoc-types >=1.12 && <1.18- , servant-docs >=0.4 && <0.11+ , servant-docs == 0.11.* , unordered-containers >=0.2 && <0.3 , text >=1.2 && <1.3 , bytestring >=0.10 && <0.11+ , string-conversions >= 0.1 && < 0.5+ , case-insensitive >= 0.2 && < 1.3 - -- Directories containing source files. hs-source-dirs: src - -- Base language which the package is written in. default-language: Haskell2010 ghc-options: -Wall
src/Servant/Docs/Pandoc.hs view
@@ -30,21 +30,23 @@ -- >> pandoc -o api.pdf --filter=api.hs manual.md module Servant.Docs.Pandoc (pandoc, makeFilter) where -import qualified Text.Pandoc.Builder as B-import Text.Pandoc.Builder (Blocks, Inlines)-import Text.Pandoc.Definition (Pandoc)-import Text.Pandoc.JSON (toJSONFilter)-import Servant.Docs-import Network.HTTP.Media (MediaType)-import qualified Data.HashMap.Strict as HM-import Data.Text (Text, unpack)-import Data.Monoid ((<>), mempty, mconcat)-import Data.List (intercalate, sort)-import Data.Foldable (foldMap)-import Data.ByteString.Lazy (ByteString)+import Control.Lens ((^.))+import Data.ByteString.Lazy (ByteString) import qualified Data.ByteString.Lazy.Char8 as B (unpack)-import Control.Lens ((^.))-+import Data.CaseInsensitive (foldedCase)+import Data.Foldable (foldMap)+import qualified Data.HashMap.Strict as HM+import Data.List (intercalate, sort)+import Data.Monoid (mconcat, mempty, (<>))+import Data.String.Conversions (convertString)+import Data.Text (Text, unpack)+import Network.HTTP.Media (MediaType)+import qualified Network.HTTP.Media as M+import Servant.Docs+import Text.Pandoc.Builder (Blocks, Inlines)+import qualified Text.Pandoc.Builder as B+import Text.Pandoc.Definition (Pandoc)+import Text.Pandoc.JSON (toJSONFilter) -- | Helper function which can be used to make a pandoc filter which -- appends the generate docs to the end of the document.@@ -70,7 +72,7 @@ capturesStr (action ^. captures) <> headersStr (action ^. headers) <> paramsStr (action ^. params) <>- rqbodyStrs (action ^. rqbody) <>+ rqbodyStrs (action ^. rqtypes) (action ^. rqbody) <> responseStr (action ^. response) where str :: Inlines@@ -138,34 +140,50 @@ where values = param ^. paramValues - rqbodyStrs :: [(MediaType, ByteString)] -> Blocks- rqbodyStrs [] = mempty- rqbodyStrs bs =+ rqbodyStrs :: [MediaType] -> [(Text, MediaType, ByteString)] -> Blocks+ rqbodyStrs [] [] = mempty+ rqbodyStrs types bs = B.header 2 "Request Body" <>- foldMap bodyStr bs+ formatTypes types <>+ B.bulletList (map bodyStr bs) - bodyStr :: (MediaType, ByteString) -> Blocks- bodyStr (media, bs) = case show media of- "text/html" -> codeStr "html" bs- "application/json" -> codeStr "javascript" bs- _ -> codeStr "text" bs+ formatTypes [] = mempty+ formatTypes ts = B.bulletList+ [ B.plain "Supported content types are:"+ , B.bulletList (map (B.plain . B.code . show) ts)+ ] - codeStr :: String -> ByteString -> Blocks- codeStr lang b =- B.codeBlockWith ("",[lang],[]) (B.unpack b)+ bodyStr :: (Text, MediaType, ByteString) -> Blocks+ bodyStr (t, media, bs) = mconcat+ [ B.plain . mconcat $+ [ "Example ("+ , B.text (convertString t)+ , "): "+ , B.code (show media)+ ]+ , codeStr media bs+ ] + codeStr :: MediaType -> ByteString -> Blocks+ codeStr media b =+ B.codeBlockWith ("",[markdownForType media],[]) (B.unpack b)+ responseStr :: Response -> Blocks responseStr resp = B.header 2 "Response" <> B.bulletList (- [B.plain $ "Status code" <> B.space <> (B.str . show) (resp ^. respStatus)]- +++ (B.plain $ "Status code" <> B.space <> (B.str . show) (resp ^. respStatus)) :+ formatTypes (resp ^. respTypes) : case resp ^. respBody of [] -> [B.plain "No response body"]- xs -> map renderResponse xs)+ [("", t, r)] -> [B.plain "Response body as below.", codeStr t r]+ xs -> concatMap renderResponse xs) where- renderResponse ("", media, r) =- B.plain (B.str $ "Response body (" <> show media <> ")") <> bodyStr (media, r)- renderResponse (ctx, media, r) =- B.plain (B.str $ unpack ctx <> " (" <> show media <> ")") <> bodyStr (media, r)+ renderResponse :: (Text, MediaType, ByteString) -> [Blocks]+ renderResponse (ctx, t, r) = [B.plain (B.str (convertString ctx)), codeStr t r] + -- Pandoc has a wide range of syntax highlighting available,+ -- many (all?) of which seem to correspond to the sub-type of+ -- their corresponding media type.+ markdownForType :: MediaType -> String+ markdownForType = convertString . foldedCase . M.subType