git.iko.soy/typeable/servant
on master help sign in
Add an option to wrap notes in a separate header
6df2003Ivan Lazar Miljenovic
servant-docs/src/Servant/Docs.hs+1−1
compare with master
unifiedsplit
@@ -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+13−4
@@ -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,16 +619,21 @@ 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 [] = []