nirum-lang · dahlia · Apr 15, 2018 · Apr 12, 2018 · Apr 12, 2018 · Apr 12, 2018
diff --git a/CHANGES.md b/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

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -79,6 +79,6 @@ dependencies):
  -  Python
      -  All Python versions that Nirum should support: Python 2.7, and
         3.4 and above all
-     -  [`tox`][tox]
+     -  [`tox`][tox] 3.0.0 or higher
 
 [tox]: https://tox.readthedocs.io/
diff --git a/examples/builtins.nrm b/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,

diff --git a/src/Nirum/Docs.hs b/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]

diff --git a/src/Nirum/Targets/Docs.hs b/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
@@ -156,10 +157,14 @@ module' :: BoundModule Docs -> Html
 module' docsModule =
     layout pkg depth (ModulePage docsModulePath) title $ [shamlet|
 $maybe tit <- headingTitle
-    <h1><code>#{path}</code>
-    <p>#{tit}
+    <h1>
+        <dfn><code>#{path}</code>
+        &#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}
@@ -195,100 +200,117 @@ blockToHtml b = preEscapedToMarkup $ render b
 typeDecl :: BoundModule Docs -> Identifier -> TD.TypeDeclaration -> Html
 typeDecl mod' ident
          tc@TD.TypeDeclaration { TD.type' = TD.Alias cname } = [shamlet|
-    <h2><code>type</code> #{toNormalizedText ident} = #
-        <code>#{typeExpression mod' cname}</code>
+    <h2>
+        type <dfn><code>#{toNormalizedText ident}</code></dfn> = #
+        <code.type>#{typeExpression mod' cname}</code>
     $maybe d <- docsBlock tc
         #{blockToHtml d}
 |]
 typeDecl mod' ident
          tc@TD.TypeDeclaration { TD.type' = TD.UnboxedType innerType } =
     [shamlet|
-        <h2><code>unboxed</code> #{toNormalizedText ident}
+        <h2>
+            unboxed
+            <dfn><code>#{toNormalizedText ident}</code>
             (<code>#{typeExpression mod' innerType}</code>)
         $maybe d <- docsBlock tc
             #{blockToHtml d}
     |]
 typeDecl _ ident
          tc@TD.TypeDeclaration { TD.type' = TD.EnumType members } = [shamlet|
-    <h2><code>enum</code> #{toNormalizedText ident}
+    <h2>enum <dfn><code>#{toNormalizedText ident}</code></dfn>
     $maybe d <- docsBlock tc
         #{blockToHtml d}
     <dl class="members">
         $forall decl <- DES.toList members
-            <dt class="member-name">#{nameText $ DE.name decl}
+            <dt class="member-name">
+                <code>#{nameText $ DE.name decl}
             <dd class="member-doc">
                 $maybe d <- docsBlock decl
                     #{blockToHtml d}
 |]
 typeDecl mod' ident
          tc@TD.TypeDeclaration { TD.type' = TD.RecordType fields } = [shamlet|
-    <h2><code>record</code> #{toNormalizedText ident}
+    <h2>record <dfn><code>#{toNormalizedText ident}</code></dfn>
     $maybe d <- docsBlock tc
         #{blockToHtml d}
     <dl.fields>
         $forall fieldDecl@(TD.Field _ fieldType _) <- DES.toList fields
             <dt>
-                <code>#{typeExpression mod' fieldType}
-                #{nameText $ DE.name fieldDecl}
-            $maybe d <- docsBlock fieldDecl
-                <dd>#{blockToHtml d}
+                <code.type>#{typeExpression mod' fieldType}
+                <var><code>#{nameText $ DE.name fieldDecl}</code>
+            <dd>
+                $maybe d <- docsBlock fieldDecl
+                    #{blockToHtml d}
 |]
 typeDecl mod' ident
-         tc@TD.TypeDeclaration { TD.type' = TD.UnionType tags _} = [shamlet|
-    <h2>union <code>#{toNormalizedText ident}</code>
+         tc@TD.TypeDeclaration
+             { TD.type' = unionType@TD.UnionType
+                   { TD.defaultTag = defaultTag
+                   }
+             } =
+    [shamlet|
+    <h2>union <dfn><code>#{toNormalizedText ident}</code></dfn>
     $maybe d <- docsBlock tc
         #{blockToHtml d}
-    $forall tagDecl@(TD.Tag _ fields _) <- DES.toList tags
-        <h3 class="tag"><code>#{nameText $ DE.name tagDecl}</code>
+    $forall (default_, tagDecl@(TD.Tag _ fields _)) <- tagList
+        <h3 .tag :default_:.default-tag>
+            $if default_
+                default tag #
+            $else
+                tag #
+            <dfn><code>#{nameText $ DE.name tagDecl}</code>
         $maybe d <- docsBlock tagDecl
             #{blockToHtml d}
-        $forall fieldDecl@(TD.Field _ fieldType _) <- DES.toList fields
-            <h4>
-                <span.type>#{typeExpression mod' fieldType}
-                <code>#{nameText $ DE.name fieldDecl}
-            $maybe d <- docsBlock fieldDecl
-                #{blockToHtml d}
-|]
+        <dl.fields>
+            $forall fieldDecl@(TD.Field _ fieldType _) <- DES.toList fields
+                <dt>
+                    <code.type>#{typeExpression mod' fieldType}
+                    <var><code>#{nameText $ DE.name fieldDecl}</code>
+                <dd>
+                    $maybe d <- docsBlock fieldDecl
+                        #{blockToHtml d}
+    |]
+  where
+    tagList :: [(Bool, TD.Tag)]
+    tagList =
+        [ (defaultTag == Just tag, tag)
+        | tag <- DES.toList (TD.tags unionType)
+        ]
 typeDecl _ ident
          TD.TypeDeclaration { TD.type' = TD.PrimitiveType {} } = [shamlet|
     <h2>primitive <code>#{toNormalizedText ident}</code>
 |]
 typeDecl mod' ident
          tc@TD.ServiceDeclaration { TD.service = S.Service methods } =
     [shamlet|
-        <h2><code>service</code> #{toNormalizedText ident}
+        <h2>service <dfn><code>#{toNormalizedText ident}</code></dfn>
         $maybe d <- docsBlock tc
             #{blockToHtml d}
         $forall md@(S.Method _ ps ret err _) <- DES.toList methods
-            <h3.method>#{nameText $ DE.name md} (
-                $forall (i, pd@(S.Parameter _ pt _)) <- enumerateParams ps
-                    $if i > 0
-                        , #
-                    <code.type>#{typeExpression mod' pt}</code> #
-                    <var>#{nameText $ DE.name pd}</var>#
-                )
+            <h3.method>
+                $maybe retType <- ret
+                    <span.return>
+                        <code.type>#{typeExpression mod' retType}
+                        &#32;
+                <dfn>
+                    <code>#{nameText $ DE.name md}
+                    &#32;
+                <span.parentheses>()
+                $maybe errType <- err
+                    <span.error>
+                        throws
+                        <code.error.type>#{typeExpression mod' errType}
             $maybe d <- docsBlock md
                 #{blockToHtml d}
             <dl.parameters>
                 $forall paramDecl@(S.Parameter _ paramType _) <- DES.toList ps
                     $maybe d <- docsBlock paramDecl
                         <dt>
                             <code.type>#{typeExpression mod' paramType}
-                            <var>#{nameText $ DE.name paramDecl}</var>:
+                            <code><var>#{nameText $ DE.name paramDecl}</var>
                         <dd>#{blockToHtml d}
-            <dl.result>
-                $maybe retType <- ret
-                    <dt.return-label>returns:
-                    <dd.return-type><code>#{typeExpression mod' retType}</code>
-                $maybe errType <- err
-                    <dt.raise-label>raises:
-                    <dd.raise-type><code>#{typeExpression mod' errType}</code>
 |]
-  where
-    enumerate :: [a] -> [(Int, a)]
-    enumerate = zip [0 ..]
-    enumerateParams :: DES.DeclarationSet S.Parameter -> [(Int, S.Parameter)]
-    enumerateParams = enumerate . DES.toList
 typeDecl _ _ TD.Import {} =
     error ("It shouldn't happen; please report it to Nirum's bug tracker:\n" ++
            "https://github.com/spoqa/nirum/issues")

diff --git a/test/Nirum/DocsSpec.hs b/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
diff --git a/tox.ini b/tox.ini
@@ -1,4 +1,5 @@
 [tox]
+minversion = 3.0.0
 envlist =
     buildfixture
     # CHECK: When the list of supported Python versions change,