From 6df200326fdc58b15fdbd35952995700aaadc45f Mon Sep 17 00:00:00 2001
From: Ivan Lazar Miljenovic <Ivan.Miljenovic@gmail.com>
Date: Wed, 11 Oct 2017 12:12:48 +1100
Subject: [PATCH] Add an option to wrap notes in a separate header

Closes #831, using option 3.
---
 servant-docs/src/Servant/Docs.hs          |  2 +-
 servant-docs/src/Servant/Docs/Internal.hs | 17 +++++++++++++----
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/servant-docs/src/Servant/Docs.hs b/servant-docs/src/Servant/Docs.hs
index 5d7661fe..83699bb2 100644
--- a/servant-docs/src/Servant/Docs.hs
+++ b/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
diff --git a/servant-docs/src/Servant/Docs/Internal.hs b/servant-docs/src/Servant/Docs/Internal.hs
index 0c22e0cf..f71430d6 100644
--- a/servant-docs/src/Servant/Docs/Internal.hs
+++ b/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 [] = []