git.iko.soy/servant
on master help sign in
Merge pull request #834 from ivan-m/group-notes-together
6028062Alp Mestanogullari
servant-docs/CHANGELOG.md+4−2
compare with master
unifiedsplit
@@ -7,8 +7,10 @@
7* Document the HTTP Method the parameters of an endpoint belong to
7* Document the HTTP Method the parameters of an endpoint belong to
8 (rather than assuming `GET` for all of them).
8 (rather than assuming `GET` for all of them).
9* Content type of sample response body is also displayed.
9* Content type of sample response body is also displayed.
10+* Can now customise various aspects of how the document is produced
11+ using `markdownWith` and `RenderingOptions`:
10−* Can now control how many content-types for each example are shown
12+ - How many content-types for each example are shown
11− with `markdownWith` and `RenderingOptions`.
13+ - Whether notes should be grouped together under their own header.
12
14
130.11
150.11
14----
16----
servant-docs/src/Servant/Docs.hs+1−1
@@ -26,7 +26,7 @@ module Servant.Docs
26 HasDocs(..), docs, pretty, markdown
26 HasDocs(..), docs, pretty, markdown
27 -- ** Customising generated documentation
27 -- ** Customising generated documentation
28 , markdownWith, RenderingOptions(..), defRenderingOptions
28 , markdownWith, RenderingOptions(..), defRenderingOptions
29− , requestExamples, responseExamples, ShowContentTypes(..)
29+ , requestExamples, responseExamples, ShowContentTypes(..), notesHeading
30 -- * Generating docs with extra information
30 -- * Generating docs with extra information
31 , docsWith, docsWithIntros, docsWithOptions
31 , docsWith, docsWithIntros, docsWithOptions
32 , ExtraInfo(..), extraInfo
32 , ExtraInfo(..), extraInfo
servant-docs/src/Servant/Docs/Internal.hs+19−10
@@ -313,18 +313,22 @@ data RenderingOptions = RenderingOptions
313 -- ^ How many content types to display for request body examples?
313 -- ^ How many content types to display for request body examples?
314 , _responseExamples :: !ShowContentTypes
314 , _responseExamples :: !ShowContentTypes
315 -- ^ How many content types to display for response body examples?
315 -- ^ How many content types to display for response body examples?
316+ , _notesHeading :: !(Maybe String)
317+ -- ^ Optionally group all 'notes' together under a common heading.
316 } deriving (Show)
318 } deriving (Show)
317
319
318-- | Default API generation options.
320-- | Default API generation options.
319--
321--
320-- All content types are shown for both 'requestExamples' and
322-- All content types are shown for both 'requestExamples' and
321−-- 'responseExamples'.
323+-- 'responseExamples'; 'notesHeading' is set to 'Nothing'
324+-- (i.e. un-grouped).
322--
325--
323-- @since 0.11.1
326-- @since 0.11.1
324defRenderingOptions :: RenderingOptions
327defRenderingOptions :: RenderingOptions
325defRenderingOptions = RenderingOptions
328defRenderingOptions = RenderingOptions
326 { _requestExamples = AllContentTypes
329 { _requestExamples = AllContentTypes
327 , _responseExamples = AllContentTypes
330 , _responseExamples = AllContentTypes
331+ , _notesHeading = Nothing
328 }
332 }
329
333
330-- gimme some lenses
334-- gimme some lenses
@@ -615,23 +619,28 @@ markdownWith RenderingOptions{..} api = unlines $
615 []
619 []
616
620
617 notesStr :: [DocNote] -> [String]
621 notesStr :: [DocNote] -> [String]
622+ notesStr = addHeading
618− notesStr = concatMap noteStr
623+ . concatMap noteStr
624+ where
625+ addHeading nts = maybe nts (\hd -> ("### " ++ hd) : "" : nts) _notesHeading
619
626
620 noteStr :: DocNote -> [String]
627 noteStr :: DocNote -> [String]
621 noteStr nt =
628 noteStr nt =
622− ("#### " ++ nt ^. noteTitle) :
629+ (hdr ++ nt ^. noteTitle) :
623 "" :
630 "" :
624 intersperse "" (nt ^. noteBody) ++
631 intersperse "" (nt ^. noteBody) ++
625 "" :
632 "" :
626 []
633 []
627−
634+ where
635+ hdr | isJust _notesHeading = "#### "
636+ | otherwise = "### "
628
637
629 authStr :: [DocAuthentication] -> [String]
638 authStr :: [DocAuthentication] -> [String]
630 authStr [] = []
639 authStr [] = []
631 authStr auths =
640 authStr auths =
632 let authIntros = mapped %~ view authIntro $ auths
641 let authIntros = mapped %~ view authIntro $ auths
633 clientInfos = mapped %~ view authDataRequired $ auths
642 clientInfos = mapped %~ view authDataRequired $ auths
634− in "#### Authentication":
643+ in "### Authentication":
635 "":
644 "":
636 unlines authIntros :
645 unlines authIntros :
637 "":
646 "":
@@ -643,7 +652,7 @@ markdownWith RenderingOptions{..} api = unlines $
643 capturesStr :: [DocCapture] -> [String]
652 capturesStr :: [DocCapture] -> [String]
644 capturesStr [] = []
653 capturesStr [] = []
645 capturesStr l =
654 capturesStr l =
646− "#### Captures:" :
655+ "### Captures:" :
647 "" :
656 "" :
648 map captureStr l ++
657 map captureStr l ++
649 "" :
658 "" :
@@ -655,7 +664,7 @@ markdownWith RenderingOptions{..} api = unlines $
655 headersStr :: [Text] -> [String]
664 headersStr :: [Text] -> [String]
656 headersStr [] = []
665 headersStr [] = []
657 headersStr l =
666 headersStr l =
658− "#### Headers:" :
667+ "### Headers:" :
659 "" :
668 "" :
660 map headerStr l ++
669 map headerStr l ++
661 "" :
670 "" :
@@ -667,7 +676,7 @@ markdownWith RenderingOptions{..} api = unlines $
667 paramsStr :: HTTP.Method -> [DocQueryParam] -> [String]
676 paramsStr :: HTTP.Method -> [DocQueryParam] -> [String]
668 paramsStr _ [] = []
677 paramsStr _ [] = []
669 paramsStr m l =
678 paramsStr m l =
670− ("#### " ++ cs m ++ " Parameters:") :
679+ ("### " ++ cs m ++ " Parameters:") :
671 "" :
680 "" :
672 map (paramStr m) l ++
681 map (paramStr m) l ++
673 "" :
682 "" :
@@ -693,7 +702,7 @@ markdownWith RenderingOptions{..} api = unlines $
693 rqbodyStr :: [M.MediaType] -> [(Text, M.MediaType, ByteString)]-> [String]
702 rqbodyStr :: [M.MediaType] -> [(Text, M.MediaType, ByteString)]-> [String]
694 rqbodyStr [] [] = []
703 rqbodyStr [] [] = []
695 rqbodyStr types s =
704 rqbodyStr types s =
696− ["#### Request:", ""]
705+ ["### Request:", ""]
697 <> formatTypes types
706 <> formatTypes types
698 <> formatBodies _requestExamples s
707 <> formatBodies _requestExamples s
699
708
@@ -749,7 +758,7 @@ markdownWith RenderingOptions{..} api = unlines $
749
758
750 responseStr :: Response -> [String]
759 responseStr :: Response -> [String]
751 responseStr resp =
760 responseStr resp =
752− "#### Response:" :
761+ "### Response:" :
753 "" :
762 "" :
754 ("- Status code " ++ show (resp ^. respStatus)) :
763 ("- Status code " ++ show (resp ^. respStatus)) :
755 ("- Headers: " ++ show (resp ^. respHeaders)) :
764 ("- Headers: " ++ show (resp ^. respHeaders)) :