digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-09-20 01:07:18 +03:00
Code Issues Projects Releases Wiki Activity

damldocs: Switch to mustache templates. (#2373)

Browse Source 
* damldocs: Switch to mustache templates.

* Update cli help and release notes.

* Move to stache
This commit is contained in:
associahedron 2019-08-02 14:52:38 +01:00 committed by mergify[bot]
parent 6e841952c0
commit 7d165a7511
6 changed files with 30 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
compiler/damlc/base-md-template.md
View File

@ -13,4 +13,4 @@ import DA.Optional
import DA.Time
```
__BODY__
{{{body}}}

2
compiler/damlc/base-rst-template.rst
View File

@ -19,4 +19,4 @@ be used straight out of the box. You can import modules from the standard librar
import DA.Optional
import DA.Time
__BODY__
{{{body}}}

1
compiler/damlc/daml-doc/BUILD.bazel
View File

@ -28,6 +28,7 @@ da_haskell_library(
"hashable",
"mtl",
"prettyprinter",
"stache",
"text",
"transformers",
],

35
compiler/damlc/daml-doc/src/DA/Daml/Doc/Render.hs
View File

@ -1,7 +1,6 @@
-- Copyright (c) 2019 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
-- SPDX-License-Identifier: Apache-2.0
module DA.Daml.Doc.Render
( RenderFormat(..)
, RenderOptions(..)
@ -28,14 +27,18 @@ import Data.List.Extra
import Data.Foldable
import System.Directory
import System.FilePath
import System.IO
import System.Exit
import qualified CMarkGFM as GFM
import qualified Data.Aeson.Types as A
import qualified Data.Aeson.Encode.Pretty as AP
import qualified Data.Text as T
import qualified Data.Text.Lazy as TL
import qualified Data.Text.Encoding as T
import qualified Data.ByteString as BS
import qualified Data.Map.Strict as Map
import qualified Text.Mustache as M
-- | centralised JSON configuration for pretty-printing
jsonConf :: AP.Config
@ -48,7 +51,9 @@ renderDocs RenderOptions{..} mods = do
Rst -> (renderRst, id)
Markdown -> (renderMd, id)
Html -> (renderMd, GFM.commonmarkToHtml [GFM.optUnsafe] [GFM.extTable])
template = fromMaybe (defaultTemplate ro_format) ro_template
templateText = fromMaybe (defaultTemplate ro_format) ro_template
template <- compileTemplate templateText
case ro_mode of
RenderToFile path -> do
@ -84,26 +89,34 @@ renderDocs RenderOptions{..} mods = do
. postProcessing
$ renderedOutput
compileTemplate :: T.Text -> IO M.Template
compileTemplate templateText =
case M.compileMustacheText "daml docs template" templateText of
Right t -> pure t
Left e -> do
hPutStrLn stderr ("Error with daml docs template: " <> show e)
exitFailure
renderTemplate ::
T.Text -- ^ template
M.Template -- ^ template
-> T.Text -- ^ page title
-> T.Text -- ^ page body
-> T.Text
renderTemplate template pageTitle pageBody
= T.replace "__BODY__" pageBody
. T.replace "__TITLE__" pageTitle
$ template
renderTemplate template pageTitle pageBody =
TL.toStrict . M.renderMustache template . A.object $
[ "title" A..= pageTitle
, "body" A..= pageBody
]
defaultTemplate :: RenderFormat -> T.Text
defaultTemplate = \case
Html -> defaultTemplateHtml
_ -> "__BODY__"
_ -> "{{{body}}}"
defaultTemplateHtml :: T.Text
defaultTemplateHtml = T.unlines
[ "<html>"
, "<head><title>__TITLE__</title><meta charset=\"utf-8\"></head>"
, "<body>__BODY__</body>"
, "<head><title>{{title}}</title><meta charset=\"utf-8\"></head>"
, "<body>{{{body}}}</body>"
, "</html>"
]

2
compiler/damlc/lib/DA/Cli/Damlc/Command/Damldoc.hs
View File

@ -71,7 +71,7 @@ documentation = Damldoc
optTemplate =
optional . option str
$ metavar "FILE"
<> help "Path to output template for generated files. When generating docs, __TITLE__ and __BODY__ in the template are replaced with doc title and body respectively, before output. (Exception: for hoogle and json output, the template file is a prefix to the body, no replacement occurs.)" -- TODO: make template behavior uniform accross formats
<> help "Path to mustache template. The variables 'title' and 'body' in the template are substituted with the doc title and body respectively. (Exception: for hoogle and json output, the template file is a prefix to the body, no replacement occurs.)" -- TODO: make template behavior uniform accross formats
<> long "template"
<> short 't'

2
unreleased.rst
View File

@ -8,3 +8,5 @@ This page contains release notes for the SDK.
HEAD — ongoing
--------------
+ [DAML Docs] For ``damlc docs``, the ``--template`` argument now takes the path to a Mustache template when generating Markdown, Rst, and HTML output. The template can use ``title`` and ``body`` variables to control the appearance of the docs.