diff --git a/CHANGELOG b/CHANGELOG new file mode 100644 --- /dev/null +++ b/CHANGELOG @@ -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 diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -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 +```` diff --git a/servant-pandoc.cabal b/servant-pandoc.cabal --- a/servant-pandoc.cabal +++ b/servant-pandoc.cabal @@ -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 . - --- 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 diff --git a/src/Servant/Docs/Pandoc.hs b/src/Servant/Docs/Pandoc.hs --- a/src/Servant/Docs/Pandoc.hs +++ b/src/Servant/Docs/Pandoc.hs @@ -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