Skip to content

Commit ac4b2db

Browse files
dahliadahlia
authored
Merge pull request #259 from dahlia/show-default-tag-on-docs
Several improvements on docs target
2 parents 0b08904 + dc13fd9 commit ac4b2db

File tree

7 files changed

+98
-58
lines changed

7 files changed

+98
-58
lines changed

‎CHANGES.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,9 @@ To be released.
126126
127127
- Docs now have a sidebar which contains table of contents. [[#257]]
128128
129+
- Fixed a bug that a module-level docs hadn't been rendered.
130+
Now it's shown in the right below the module name. [[#259]]
131+
129132
### Python target
130133
131134
- Generated Python packages became to have two [entry points] (a feature
@@ -178,6 +181,7 @@ To be released.
178181
[#254]: https://github.com/spoqa/nirum/pull/254
179182
[#255]: https://github.com/spoqa/nirum/pull/255
180183
[#257]: https://github.com/spoqa/nirum/pull/257
184+
[#259]: https://github.com/spoqa/nirum/pull/259
181185
[entry points]: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
182186
[python2-numbers-integral]: https://docs.python.org/2/library/numbers.html#numbers.Integral
183187
[python2-int]: https://docs.python.org/2/library/functions.html#int

‎CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,6 @@ dependencies):
7979
- Python
8080
- All Python versions that Nirum should support: Python 2.7, and
8181
3.4 and above all
82-
- [`tox`][tox]
82+
- [`tox`][tox] 3.0.0 or higher
8383

8484
[tox]: https://tox.readthedocs.io/

‎examples/builtins.nrm

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Introducing built-in types
22
# ==========================
3+
#
4+
# This example module introduces the built-in types Nirum provides.
35

46
record number-types (
57
bigint a,

‎src/Nirum/Docs.hs

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ module Nirum.Docs ( Block ( BlockQuote
3737
, headingLevelFromInt
3838
, headingLevelInt
3939
, parse
40+
, trimTitle
4041
) where
4142

4243
import Data.String (IsString (fromString))
@@ -112,6 +113,13 @@ data Inline
112113
| Image { imageUrl :: Url, imageTitle :: Title }
113114
deriving (Eq, Ord, Show)
114115

116+
-- | Trim the top-level first heading from the block, if it exists.
117+
trimTitle :: Block -> Block
118+
trimTitle block =
119+
case block of
120+
Document (Heading {} : rest) -> Document rest
121+
b -> b
122+
115123
parse :: T.Text -> Block
116124
parse =
117125
transBlock . M.commonmarkToNode [M.optNormalize, M.optSmart]

‎src/Nirum/Targets/Docs.hs

Lines changed: 66 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ import qualified Nirum.Constructs.TypeDeclaration as TD
3939
import qualified Nirum.Constructs.TypeExpression as TE
4040
import Nirum.Docs ( Block (Heading)
4141
, filterReferences
42+
, trimTitle
4243
)
4344
import Nirum.Docs.Html (render, renderInlines)
4445
import Nirum.Package
@@ -156,10 +157,14 @@ module' :: BoundModule Docs -> Html
156157
module' docsModule =
157158
layout pkg depth (ModulePage docsModulePath) title $ [shamlet|
158159
$maybe tit <- headingTitle
159-
<h1><code>#{path}</code>
160-
<p>#{tit}
160+
<h1>
161+
<dfn><code>#{path}</code>
162+
&#32;&mdash; #{tit}
161163
$nothing
162164
<h1><code>#{path}</code>
165+
$maybe m <- mod'
166+
$maybe d <- docsBlock m
167+
#{blockToHtml (trimTitle d)}
163168
$forall (ident, decl) <- types'
164169
<div class="#{showKind decl}" id="#{toNormalizedText ident}">
165170
#{typeDecl docsModule ident decl}
@@ -195,100 +200,117 @@ blockToHtml b = preEscapedToMarkup $ render b
195200
typeDecl :: BoundModule Docs -> Identifier -> TD.TypeDeclaration -> Html
196201
typeDecl mod' ident
197202
tc@TD.TypeDeclaration { TD.type' = TD.Alias cname } = [shamlet|
198-
<h2><code>type</code> #{toNormalizedText ident} = #
199-
<code>#{typeExpression mod' cname}</code>
203+
<h2>
204+
type <dfn><code>#{toNormalizedText ident}</code></dfn> = #
205+
<code.type>#{typeExpression mod' cname}</code>
200206
$maybe d <- docsBlock tc
201207
#{blockToHtml d}
202208
|]
203209
typeDecl mod' ident
204210
tc@TD.TypeDeclaration { TD.type' = TD.UnboxedType innerType } =
205211
[shamlet|
206-
<h2><code>unboxed</code> #{toNormalizedText ident}
212+
<h2>
213+
unboxed
214+
<dfn><code>#{toNormalizedText ident}</code>
207215
(<code>#{typeExpression mod' innerType}</code>)
208216
$maybe d <- docsBlock tc
209217
#{blockToHtml d}
210218
|]
211219
typeDecl _ ident
212220
tc@TD.TypeDeclaration { TD.type' = TD.EnumType members } = [shamlet|
213-
<h2><code>enum</code> #{toNormalizedText ident}
221+
<h2>enum <dfn><code>#{toNormalizedText ident}</code></dfn>
214222
$maybe d <- docsBlock tc
215223
#{blockToHtml d}
216224
<dl class="members">
217225
$forall decl <- DES.toList members
218-
<dt class="member-name">#{nameText $ DE.name decl}
226+
<dt class="member-name">
227+
<code>#{nameText $ DE.name decl}
219228
<dd class="member-doc">
220229
$maybe d <- docsBlock decl
221230
#{blockToHtml d}
222231
|]
223232
typeDecl mod' ident
224233
tc@TD.TypeDeclaration { TD.type' = TD.RecordType fields } = [shamlet|
225-
<h2><code>record</code> #{toNormalizedText ident}
234+
<h2>record <dfn><code>#{toNormalizedText ident}</code></dfn>
226235
$maybe d <- docsBlock tc
227236
#{blockToHtml d}
228237
<dl.fields>
229238
$forall fieldDecl@(TD.Field _ fieldType _) <- DES.toList fields
230239
<dt>
231-
<code>#{typeExpression mod' fieldType}
232-
#{nameText $ DE.name fieldDecl}
233-
$maybe d <- docsBlock fieldDecl
234-
<dd>#{blockToHtml d}
240+
<code.type>#{typeExpression mod' fieldType}
241+
<var><code>#{nameText $ DE.name fieldDecl}</code>
242+
<dd>
243+
$maybe d <- docsBlock fieldDecl
244+
#{blockToHtml d}
235245
|]
236246
typeDecl mod' ident
237-
tc@TD.TypeDeclaration { TD.type' = TD.UnionType tags _} = [shamlet|
238-
<h2>union <code>#{toNormalizedText ident}</code>
247+
tc@TD.TypeDeclaration
248+
{ TD.type' = unionType@TD.UnionType
249+
{ TD.defaultTag = defaultTag
250+
}
251+
} =
252+
[shamlet|
253+
<h2>union <dfn><code>#{toNormalizedText ident}</code></dfn>
239254
$maybe d <- docsBlock tc
240255
#{blockToHtml d}
241-
$forall tagDecl@(TD.Tag _ fields _) <- DES.toList tags
242-
<h3 class="tag"><code>#{nameText $ DE.name tagDecl}</code>
256+
$forall (default_, tagDecl@(TD.Tag _ fields _)) <- tagList
257+
<h3 .tag :default_:.default-tag>
258+
$if default_
259+
default tag #
260+
$else
261+
tag #
262+
<dfn><code>#{nameText $ DE.name tagDecl}</code>
243263
$maybe d <- docsBlock tagDecl
244264
#{blockToHtml d}
245-
$forall fieldDecl@(TD.Field _ fieldType _) <- DES.toList fields
246-
<h4>
247-
<span.type>#{typeExpression mod' fieldType}
248-
<code>#{nameText $ DE.name fieldDecl}
249-
$maybe d <- docsBlock fieldDecl
250-
#{blockToHtml d}
251-
|]
265+
<dl.fields>
266+
$forall fieldDecl@(TD.Field _ fieldType _) <- DES.toList fields
267+
<dt>
268+
<code.type>#{typeExpression mod' fieldType}
269+
<var><code>#{nameText $ DE.name fieldDecl}</code>
270+
<dd>
271+
$maybe d <- docsBlock fieldDecl
272+
#{blockToHtml d}
273+
|]
274+
where
275+
tagList :: [(Bool, TD.Tag)]
276+
tagList =
277+
[ (defaultTag == Just tag, tag)
278+
| tag <- DES.toList (TD.tags unionType)
279+
]
252280
typeDecl _ ident
253281
TD.TypeDeclaration { TD.type' = TD.PrimitiveType {} } = [shamlet|
254282
<h2>primitive <code>#{toNormalizedText ident}</code>
255283
|]
256284
typeDecl mod' ident
257285
tc@TD.ServiceDeclaration { TD.service = S.Service methods } =
258286
[shamlet|
259-
<h2><code>service</code> #{toNormalizedText ident}
287+
<h2>service <dfn><code>#{toNormalizedText ident}</code></dfn>
260288
$maybe d <- docsBlock tc
261289
#{blockToHtml d}
262290
$forall md@(S.Method _ ps ret err _) <- DES.toList methods
263-
<h3.method>#{nameText $ DE.name md} (
264-
$forall (i, pd@(S.Parameter _ pt _)) <- enumerateParams ps
265-
$if i > 0
266-
, #
267-
<code.type>#{typeExpression mod' pt}</code> #
268-
<var>#{nameText $ DE.name pd}</var>#
269-
)
291+
<h3.method>
292+
$maybe retType <- ret
293+
<span.return>
294+
<code.type>#{typeExpression mod' retType}
295+
&#32;
296+
<dfn>
297+
<code>#{nameText $ DE.name md}
298+
&#32;
299+
<span.parentheses>()
300+
$maybe errType <- err
301+
<span.error>
302+
throws
303+
<code.error.type>#{typeExpression mod' errType}
270304
$maybe d <- docsBlock md
271305
#{blockToHtml d}
272306
<dl.parameters>
273307
$forall paramDecl@(S.Parameter _ paramType _) <- DES.toList ps
274308
$maybe d <- docsBlock paramDecl
275309
<dt>
276310
<code.type>#{typeExpression mod' paramType}
277-
<var>#{nameText $ DE.name paramDecl}</var>:
311+
<code><var>#{nameText $ DE.name paramDecl}</var>
278312
<dd>#{blockToHtml d}
279-
<dl.result>
280-
$maybe retType <- ret
281-
<dt.return-label>returns:
282-
<dd.return-type><code>#{typeExpression mod' retType}</code>
283-
$maybe errType <- err
284-
<dt.raise-label>raises:
285-
<dd.raise-type><code>#{typeExpression mod' errType}</code>
286313
|]
287-
where
288-
enumerate :: [a] -> [(Int, a)]
289-
enumerate = zip [0 ..]
290-
enumerateParams :: DES.DeclarationSet S.Parameter -> [(Int, S.Parameter)]
291-
enumerateParams = enumerate . DES.toList
292314
typeDecl _ _ TD.Import {} =
293315
error ("It shouldn't happen; please report it to Nirum's bug tracker:\n" ++
294316
"https://github.com/spoqa/nirum/issues")

‎test/Nirum/DocsSpec.hs

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,7 @@ import Data.Text (Text)
55
import Test.Hspec.Meta
66
import Text.InterpolatedString.Perl6 (q)
77

8-
import Nirum.Docs ( Block (..)
9-
, HeadingLevel (..)
10-
, Inline (..)
11-
, ItemList (..)
12-
, ListDelimiter (..)
13-
, ListType (..)
14-
, filterReferences
15-
, headingLevelFromInt
16-
, parse
17-
)
8+
import Nirum.Docs
189

1910
sampleSource :: Text
2011
sampleSource = [q|
@@ -38,11 +29,18 @@ A [complex *link*][1].
3829

3930
|]
4031

32+
sampleHeading :: Block
33+
sampleHeading =
34+
Heading H1 ["Hello"]
35+
4136
sampleDocument :: Block
4237
sampleDocument =
43-
Document
44-
[ Heading H1 ["Hello"]
45-
, Paragraph ["Tight list:"]
38+
sampleDocument' (sampleHeading :)
39+
40+
sampleDocument' :: ([Block] -> [Block]) -> Block
41+
sampleDocument' adjust =
42+
(Document . adjust)
43+
[ Paragraph ["Tight list:"]
4644
, List BulletList $ TightItemList [ ["List test"]
4745
, ["test2"]
4846
]
@@ -91,3 +89,8 @@ spec = do
9189
, "image"
9290
, "."
9391
]
92+
specify "trimTitle" $ do
93+
-- Remove the top-level heading if it exists:
94+
trimTitle sampleDocument `shouldBe` sampleDocument' id
95+
-- No-op if there is no top-level heading:
96+
trimTitle (sampleDocument' id) `shouldBe` sampleDocument' id

‎tox.ini

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[tox]
2+
minversion = 3.0.0
23
envlist =
34
buildfixture
45
# CHECK: When the list of supported Python versions change,

0 commit comments

Comments
 (0)