Render module-level docs

Author: Hong Minhee

CHANGES.md

@@ -126,6 +126,9 @@ To be released.
 
  -  Docs now have a sidebar which contains table of contents.  [[#257]]
 
+ -  Fixed a bug that a module-level docs hadn't been rendered.
+    Now it's shown in the right below the module name.  [[#259]]
+
 ### Python target
 
  -  Generated Python packages became to have two [entry points] (a feature
@@ -178,6 +181,7 @@ To be released.
 [#254]: https://github.com/spoqa/nirum/pull/254
 [#255]: https://github.com/spoqa/nirum/pull/255
 [#257]: https://github.com/spoqa/nirum/pull/257
+[#259]: https://github.com/spoqa/nirum/pull/259
 [entry points]: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
 [python2-numbers-integral]: https://docs.python.org/2/library/numbers.html#numbers.Integral
 [python2-int]: https://docs.python.org/2/library/functions.html#int

examples/builtins.nrm

@@ -1,5 +1,7 @@
 # Introducing built-in types
 # ==========================
+#
+# This example module introduces the built-in types Nirum provides.
 
 record number-types (
     bigint a,

src/Nirum/Docs.hs

@@ -37,6 +37,7 @@ module Nirum.Docs ( Block ( BlockQuote
                   , headingLevelFromInt
                   , headingLevelInt
                   , parse
+                  , trimTitle
                   ) where
 
 import Data.String (IsString (fromString))
@@ -112,6 +113,13 @@ data Inline
     | Image { imageUrl :: Url, imageTitle :: Title }
     deriving (Eq, Ord, Show)
 
+-- | Trim the top-level first heading from the block, if it exists.
+trimTitle :: Block -> Block
+trimTitle block =
+    case block of
+        Document (Heading {} : rest) -> Document rest
+        b -> b
+
 parse :: T.Text -> Block
 parse =
     transBlock . M.commonmarkToNode [M.optNormalize, M.optSmart]

src/Nirum/Targets/Docs.hs

@@ -39,6 +39,7 @@ import qualified Nirum.Constructs.TypeDeclaration as TD
 import qualified Nirum.Constructs.TypeExpression as TE
 import Nirum.Docs ( Block (Heading)
                   , filterReferences
+                  , trimTitle
                   )
 import Nirum.Docs.Html (render, renderInlines)
 import Nirum.Package
@@ -161,6 +162,9 @@ $maybe tit <- headingTitle
         &#32;&mdash; #{tit}
 $nothing
     <h1><code>#{path}</code>
+$maybe m <- mod'
+    $maybe d <- docsBlock m
+        #{blockToHtml (trimTitle d)}
 $forall (ident, decl) <- types'
     <div class="#{showKind decl}" id="#{toNormalizedText ident}">
         #{typeDecl docsModule ident decl}

test/Nirum/DocsSpec.hs

@@ -5,16 +5,7 @@ import Data.Text (Text)
 import Test.Hspec.Meta
 import Text.InterpolatedString.Perl6 (q)
 
-import Nirum.Docs ( Block (..)
-                  , HeadingLevel (..)
-                  , Inline (..)
-                  , ItemList (..)
-                  , ListDelimiter (..)
-                  , ListType (..)
-                  , filterReferences
-                  , headingLevelFromInt
-                  , parse
-                  )
+import Nirum.Docs
 
 sampleSource :: Text
 sampleSource = [q|
@@ -38,11 +29,18 @@ A [complex *link*][1].
 
 |]
 
+sampleHeading :: Block
+sampleHeading =
+    Heading H1 ["Hello"]
+
 sampleDocument :: Block
 sampleDocument =
-    Document
-        [ Heading H1 ["Hello"]
-        , Paragraph ["Tight list:"]
+    sampleDocument' (sampleHeading :)
+
+sampleDocument' :: ([Block] -> [Block]) -> Block
+sampleDocument' adjust =
+    (Document . adjust)
+        [ Paragraph ["Tight list:"]
         , List BulletList $ TightItemList [ ["List test"]
                                           , ["test2"]
                                           ]
@@ -91,3 +89,8 @@ spec = do
                 , "image"
                 , "."
                 ]
+    specify "trimTitle" $ do
+        -- Remove the top-level heading if it exists:
+        trimTitle sampleDocument `shouldBe` sampleDocument' id
+        -- No-op if there is no top-level heading:
+        trimTitle (sampleDocument' id) `shouldBe` sampleDocument' id