git.iko.soy/servant
on master help sign in
Merge pull request #834 from ivan-m/group-notes-together

servant-docs: Offer the ability to group notes together

commit602806296e45d91f7e9859f8fa72884647217620 authorAlp Mestanogullari <alpmestan@gmail.com> dateWed 11 Oct 2017, 11:54 (9 years ago) parentf960d970d97dea
3 files changed+24−13
compare with master
unifiedsplit
servant-docs/CHANGELOG.md+4−2 servant-docs/src/Servant/Docs.hs+1−1 servant-docs/src/Servant/Docs/Internal.hs+19−10
servant-docs/CHANGELOG.md+4−2
@@ -7,8 +7,10 @@
77* Document the HTTP Method the parameters of an endpoint belong to
88 (rather than assuming `GET` for all of them).
99* Content type of sample response body is also displayed.
10−* Can now control how many content-types for each example are shown
11− with `markdownWith` and `RenderingOptions`.
10+* Can now customise various aspects of how the document is produced
11+ using `markdownWith` and `RenderingOptions`:
12+ - How many content-types for each example are shown
13+ - Whether notes should be grouped together under their own header.
1214
13150.11
1416----
servant-docs/src/Servant/Docs.hs+1−1
@@ -26,7 +26,7 @@ module Servant.Docs
2626 HasDocs(..), docs, pretty, markdown
2727 -- ** Customising generated documentation
2828 , markdownWith, RenderingOptions(..), defRenderingOptions
29− , requestExamples, responseExamples, ShowContentTypes(..)
29+ , requestExamples, responseExamples, ShowContentTypes(..), notesHeading
3030 -- * Generating docs with extra information
3131 , docsWith, docsWithIntros, docsWithOptions
3232 , ExtraInfo(..), extraInfo
servant-docs/src/Servant/Docs/Internal.hs+19−10
@@ -313,18 +313,22 @@ data RenderingOptions = RenderingOptions
313313 -- ^ How many content types to display for request body examples?
314314 , _responseExamples :: !ShowContentTypes
315315 -- ^ How many content types to display for response body examples?
316+ , _notesHeading :: !(Maybe String)
317+ -- ^ Optionally group all 'notes' together under a common heading.
316318 } deriving (Show)
317319
318320-- | Default API generation options.
319321--
320322-- All content types are shown for both 'requestExamples' and
321−-- 'responseExamples'.
323+-- 'responseExamples'; 'notesHeading' is set to 'Nothing'
324+-- (i.e. un-grouped).
322325--
323326-- @since 0.11.1
324327defRenderingOptions :: RenderingOptions
325328defRenderingOptions = RenderingOptions
326329 { _requestExamples = AllContentTypes
327330 , _responseExamples = AllContentTypes
331+ , _notesHeading = Nothing
328332 }
329333
330334-- gimme some lenses
@@ -615,23 +619,28 @@ markdownWith RenderingOptions{..} api = unlines $
615619 []
616620
617621 notesStr :: [DocNote] -> [String]
618− notesStr = concatMap noteStr
622+ notesStr = addHeading
623+ . concatMap noteStr
624+ where
625+ addHeading nts = maybe nts (\hd -> ("### " ++ hd) : "" : nts) _notesHeading
619626
620627 noteStr :: DocNote -> [String]
621628 noteStr nt =
622− ("#### " ++ nt ^. noteTitle) :
629+ (hdr ++ nt ^. noteTitle) :
623630 "" :
624631 intersperse "" (nt ^. noteBody) ++
625632 "" :
626633 []
627−
634+ where
635+ hdr | isJust _notesHeading = "#### "
636+ | otherwise = "### "
628637
629638 authStr :: [DocAuthentication] -> [String]
630639 authStr [] = []
631640 authStr auths =
632641 let authIntros = mapped %~ view authIntro $ auths
633642 clientInfos = mapped %~ view authDataRequired $ auths
634− in "#### Authentication":
643+ in "### Authentication":
635644 "":
636645 unlines authIntros :
637646 "":
@@ -643,7 +652,7 @@ markdownWith RenderingOptions{..} api = unlines $
643652 capturesStr :: [DocCapture] -> [String]
644653 capturesStr [] = []
645654 capturesStr l =
646− "#### Captures:" :
655+ "### Captures:" :
647656 "" :
648657 map captureStr l ++
649658 "" :
@@ -655,7 +664,7 @@ markdownWith RenderingOptions{..} api = unlines $
655664 headersStr :: [Text] -> [String]
656665 headersStr [] = []
657666 headersStr l =
658− "#### Headers:" :
667+ "### Headers:" :
659668 "" :
660669 map headerStr l ++
661670 "" :
@@ -667,7 +676,7 @@ markdownWith RenderingOptions{..} api = unlines $
667676 paramsStr :: HTTP.Method -> [DocQueryParam] -> [String]
668677 paramsStr _ [] = []
669678 paramsStr m l =
670− ("#### " ++ cs m ++ " Parameters:") :
679+ ("### " ++ cs m ++ " Parameters:") :
671680 "" :
672681 map (paramStr m) l ++
673682 "" :
@@ -693,7 +702,7 @@ markdownWith RenderingOptions{..} api = unlines $
693702 rqbodyStr :: [M.MediaType] -> [(Text, M.MediaType, ByteString)]-> [String]
694703 rqbodyStr [] [] = []
695704 rqbodyStr types s =
696− ["#### Request:", ""]
705+ ["### Request:", ""]
697706 <> formatTypes types
698707 <> formatBodies _requestExamples s
699708
@@ -749,7 +758,7 @@ markdownWith RenderingOptions{..} api = unlines $
749758
750759 responseStr :: Response -> [String]
751760 responseStr resp =
752− "#### Response:" :
761+ "### Response:" :
753762 "" :
754763 ("- Status code " ++ show (resp ^. respStatus)) :
755764 ("- Headers: " ++ show (resp ^. respHeaders)) :