git.iko.soy/servant
on master help sign in
Add an option to wrap notes in a separate header

Closes #831, using option 3.

commit6df200326fdc58b15fdbd35952995700aaadc45f authorIvan Lazar Miljenovic <Ivan.Miljenovic@gmail.com> dateWed 11 Oct 2017, 12:12 (9 years ago) parent9d10fe1
2 files changed+14−5
compare with master
unifiedsplit
servant-docs/src/Servant/Docs.hs+1−1 servant-docs/src/Servant/Docs/Internal.hs+13−4
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+13−4
@@ -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,16 +619,21 @@ 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 [] = []