Add an option to wrap notes in a separate header
Closes #831, using option 3.
This commit is contained in:
parent
9d10fe13dd
commit
6df200326f
2 changed files with 14 additions and 5 deletions
servant-docs/src/Servant
|
@ -26,7 +26,7 @@ module Servant.Docs
|
||||||
HasDocs(..), docs, pretty, markdown
|
HasDocs(..), docs, pretty, markdown
|
||||||
-- ** Customising generated documentation
|
-- ** Customising generated documentation
|
||||||
, markdownWith, RenderingOptions(..), defRenderingOptions
|
, markdownWith, RenderingOptions(..), defRenderingOptions
|
||||||
, requestExamples, responseExamples, ShowContentTypes(..)
|
, requestExamples, responseExamples, ShowContentTypes(..), notesHeading
|
||||||
-- * Generating docs with extra information
|
-- * Generating docs with extra information
|
||||||
, docsWith, docsWithIntros, docsWithOptions
|
, docsWith, docsWithIntros, docsWithOptions
|
||||||
, ExtraInfo(..), extraInfo
|
, ExtraInfo(..), extraInfo
|
||||||
|
|
|
@ -313,18 +313,22 @@ data RenderingOptions = RenderingOptions
|
||||||
-- ^ How many content types to display for request body examples?
|
-- ^ How many content types to display for request body examples?
|
||||||
, _responseExamples :: !ShowContentTypes
|
, _responseExamples :: !ShowContentTypes
|
||||||
-- ^ How many content types to display for response body examples?
|
-- ^ How many content types to display for response body examples?
|
||||||
|
, _notesHeading :: !(Maybe String)
|
||||||
|
-- ^ Optionally group all 'notes' together under a common heading.
|
||||||
} deriving (Show)
|
} deriving (Show)
|
||||||
|
|
||||||
-- | Default API generation options.
|
-- | Default API generation options.
|
||||||
--
|
--
|
||||||
-- All content types are shown for both 'requestExamples' and
|
-- All content types are shown for both 'requestExamples' and
|
||||||
-- 'responseExamples'.
|
-- 'responseExamples'; 'notesHeading' is set to 'Nothing'
|
||||||
|
-- (i.e. un-grouped).
|
||||||
--
|
--
|
||||||
-- @since 0.11.1
|
-- @since 0.11.1
|
||||||
defRenderingOptions :: RenderingOptions
|
defRenderingOptions :: RenderingOptions
|
||||||
defRenderingOptions = RenderingOptions
|
defRenderingOptions = RenderingOptions
|
||||||
{ _requestExamples = AllContentTypes
|
{ _requestExamples = AllContentTypes
|
||||||
, _responseExamples = AllContentTypes
|
, _responseExamples = AllContentTypes
|
||||||
|
, _notesHeading = Nothing
|
||||||
}
|
}
|
||||||
|
|
||||||
-- gimme some lenses
|
-- gimme some lenses
|
||||||
|
@ -615,16 +619,21 @@ markdownWith RenderingOptions{..} api = unlines $
|
||||||
[]
|
[]
|
||||||
|
|
||||||
notesStr :: [DocNote] -> [String]
|
notesStr :: [DocNote] -> [String]
|
||||||
notesStr = concatMap noteStr
|
notesStr = addHeading
|
||||||
|
. concatMap noteStr
|
||||||
|
where
|
||||||
|
addHeading nts = maybe nts (\hd -> ("### " ++ hd) : "" : nts) _notesHeading
|
||||||
|
|
||||||
noteStr :: DocNote -> [String]
|
noteStr :: DocNote -> [String]
|
||||||
noteStr nt =
|
noteStr nt =
|
||||||
("### " ++ nt ^. noteTitle) :
|
(hdr ++ nt ^. noteTitle) :
|
||||||
"" :
|
"" :
|
||||||
intersperse "" (nt ^. noteBody) ++
|
intersperse "" (nt ^. noteBody) ++
|
||||||
"" :
|
"" :
|
||||||
[]
|
[]
|
||||||
|
where
|
||||||
|
hdr | isJust _notesHeading = "#### "
|
||||||
|
| otherwise = "### "
|
||||||
|
|
||||||
authStr :: [DocAuthentication] -> [String]
|
authStr :: [DocAuthentication] -> [String]
|
||||||
authStr [] = []
|
authStr [] = []
|
||||||
|
|
Loading…
Add table
Reference in a new issue