eeva/servant
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add an option to wrap notes in a separate header

Browse Source 
Closes #831, using option 3.
This commit is contained in:
Ivan Lazar Miljenovic 2017-10-11 12:12:48 +11:00
parent 9d10fe13dd
commit 6df200326f
2 changed files with 14 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
servant-docs/src/Servant/Docs.hs
View File

@ -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

17
servant-docs/src/Servant/Docs/Internal.hs
View File

@ -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 [] = []