Add an option to wrap notes in a separate header

Closes #831, using option 3.

servant-docs/src/Servant/Docs.hs

@@ -26,7 +26,7 @@ module Servant.Docs
     HasDocs(..), docs, pretty, markdown
     -- ** Customising generated documentation
   , markdownWith, RenderingOptions(..), defRenderingOptions
-  , requestExamples, responseExamples, ShowContentTypes(..)
+  , requestExamples, responseExamples, ShowContentTypes(..), notesHeading
     -- * Generating docs with extra information
   , docsWith, docsWithIntros, docsWithOptions
   , ExtraInfo(..), extraInfo

servant-docs/src/Servant/Docs/Internal.hs

@@ -313,18 +313,22 @@ data RenderingOptions = RenderingOptions
     -- ^ How many content types to display for request body examples?
   , _responseExamples :: !ShowContentTypes
     -- ^ How many content types to display for response body examples?
+  , _notesHeading     :: !(Maybe String)
+    -- ^ Optionally group all 'notes' together under a common heading.
   } deriving (Show)
 
 -- | Default API generation options.
 --
 --   All content types are shown for both 'requestExamples' and
---   'responseExamples'.
+--   'responseExamples'; 'notesHeading' is set to 'Nothing'
+--   (i.e. un-grouped).
 --
 --   @since 0.11.1
 defRenderingOptions :: RenderingOptions
 defRenderingOptions = RenderingOptions
   { _requestExamples  = AllContentTypes
   , _responseExamples = AllContentTypes
+  , _notesHeading     = Nothing
   }
 
 -- gimme some lenses
@@ -615,16 +619,21 @@ markdownWith RenderingOptions{..}  api = unlines $
             []
 
         notesStr :: [DocNote] -> [String]
-        notesStr = concatMap noteStr
+        notesStr = addHeading
+                   . concatMap noteStr
+          where
+            addHeading nts = maybe nts (\hd -> ("### " ++ hd) : "" : nts) _notesHeading
 
         noteStr :: DocNote -> [String]
         noteStr nt =
-            ("### " ++ nt ^. noteTitle) :
+            (hdr ++ nt ^. noteTitle) :
             "" :
             intersperse "" (nt ^. noteBody) ++
             "" :
             []
-
+          where
+            hdr | isJust _notesHeading = "#### "
+                | otherwise            = "### "
 
         authStr :: [DocAuthentication] -> [String]
         authStr [] = []