mirror of
https://github.com/digital-asset/daml.git
synced 2024-09-20 01:07:18 +03:00
daml-docs: Generate Hoogle database with anchor table from generating docs. (#5704)
* Fix all DAML hoogle links. This PR changes how the hoogle database is rendered in damldocs, so it has access to the mapping of anchors to URLs that is produced during rendering of rst docs. This way these will not get out of sync. I also added an --output-anchor option in preparation for fixing external/cross-package references. changelog_begin changelog_end * Update settings.json undo accidental vscode settings change. * Update README.md
This commit is contained in:
parent
15354c3256
commit
6047cca194
@ -249,36 +249,15 @@ genrule(
|
||||
)
|
||||
|
||||
genrule(
|
||||
name = "daml-base-hoogle-docs",
|
||||
name = "daml-base-docs",
|
||||
srcs = [
|
||||
":daml-prim.json",
|
||||
":daml-stdlib.json",
|
||||
":daml-base-hoogle-template",
|
||||
],
|
||||
outs = ["daml-base-hoogle.txt"],
|
||||
cmd = """
|
||||
$(location //compiler/damlc) -- docs \
|
||||
--output=$(OUTS) \
|
||||
--input-format=json \
|
||||
--format=Hoogle \
|
||||
--exclude-instances=HasField \
|
||||
--drop-orphan-instances \
|
||||
--template=$(location :daml-base-hoogle-template) \
|
||||
$(location :daml-stdlib.json) $(location :daml-prim.json)
|
||||
""",
|
||||
tools = ["//compiler/damlc"],
|
||||
visibility = ["//visibility:public"],
|
||||
)
|
||||
|
||||
genrule(
|
||||
name = "daml-base-rst-docs",
|
||||
srcs = [
|
||||
":daml-prim.json",
|
||||
":daml-stdlib.json",
|
||||
":daml-base-rst-index-template",
|
||||
":daml-base-rst-template",
|
||||
],
|
||||
outs = ["daml-base-rst.tar.gz"],
|
||||
outs = ["daml-base-rst.tar.gz", "daml-base-hoogle.txt"],
|
||||
cmd = """
|
||||
$(location //compiler/damlc) -- docs \
|
||||
--output=daml-base-rst \
|
||||
@ -288,10 +267,13 @@ genrule(
|
||||
--drop-orphan-instances \
|
||||
--template=$(location :daml-base-rst-template) \
|
||||
--index-template=$(location :daml-base-rst-index-template) \
|
||||
--hoogle-template=$(location :daml-base-hoogle-template) \
|
||||
--base-url=https://docs.daml.com/daml/stdlib \
|
||||
--output-hoogle=$(location :daml-base-hoogle.txt) \
|
||||
$(location :daml-stdlib.json) $(location :daml-prim.json)
|
||||
tar c daml-base-rst \
|
||||
--owner=0 --group=0 --numeric-owner --mtime=2000-01-01\ 00:00Z --sort=name \
|
||||
| gzip -n > $(OUTS)
|
||||
| gzip -n > $(location :daml-base-rst.tar.gz)
|
||||
""",
|
||||
tools = ["//compiler/damlc"],
|
||||
visibility = ["//visibility:public"],
|
||||
|
@ -96,10 +96,11 @@ to accept the current documentation as new golden files.
|
||||
Standard library docs are exposed under the bazel rules which you can build with:
|
||||
|
||||
```
|
||||
bazel build //compiler/damlc:daml-base-rst-docs
|
||||
bazel build //compiler/damlc:daml-base-hoogle-docs
|
||||
bazel build //compiler/damlc:daml-base-docs
|
||||
```
|
||||
|
||||
This creates a tarball containing RST (ReStructured Text) docs, and a hoogle database.
|
||||
|
||||
## DAML Packages and Database
|
||||
|
||||
A DAML project is compiled to a DAML package and can be distributed as a DAML archive (DAR). This is
|
||||
|
@ -5,6 +5,8 @@
|
||||
-- All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited.
|
||||
|
||||
-- | DAML standard library.
|
||||
@url https://docs.daml.com/daml/stdlib/index.html
|
||||
@package base
|
||||
@url {{base-url}}
|
||||
@package daml-stdlib
|
||||
@version 1.2.0
|
||||
|
||||
{{{body}}}
|
@ -44,17 +44,21 @@ data DamldocOptions = DamldocOptions
|
||||
, do_outputFormat :: OutputFormat
|
||||
, do_docTemplate :: Maybe FilePath
|
||||
, do_docIndexTemplate :: Maybe FilePath
|
||||
, do_docHoogleTemplate :: Maybe FilePath
|
||||
, do_transformOptions :: TransformOptions
|
||||
, do_inputFiles :: [NormalizedFilePath]
|
||||
, do_docTitle :: Maybe T.Text
|
||||
, do_combine :: Bool
|
||||
, do_extractOptions :: ExtractOptions
|
||||
, do_baseURL :: Maybe T.Text -- ^ base URL for generated documentation
|
||||
, do_hooglePath :: Maybe FilePath -- ^ hoogle database output path
|
||||
, do_anchorPath :: Maybe FilePath -- ^ anchor table output path
|
||||
}
|
||||
|
||||
data InputFormat = InputJson | InputDaml
|
||||
deriving (Eq, Show, Read)
|
||||
|
||||
data OutputFormat = OutputJson | OutputHoogle | OutputDocs RenderFormat
|
||||
data OutputFormat = OutputJson | OutputDocs RenderFormat
|
||||
deriving (Eq, Show, Read)
|
||||
|
||||
-- | Run damldocs!
|
||||
@ -92,6 +96,7 @@ renderDocData :: DamldocOptions -> [ModuleDoc] -> IO ()
|
||||
renderDocData DamldocOptions{..} docData = do
|
||||
templateM <- mapM T.readFileUtf8 do_docTemplate
|
||||
indexTemplateM <- mapM T.readFileUtf8 do_docIndexTemplate
|
||||
hoogleTemplateM <- mapM T.readFileUtf8 do_docHoogleTemplate
|
||||
|
||||
let prefix = fromMaybe "" templateM
|
||||
write file contents = do
|
||||
@ -102,8 +107,6 @@ renderDocData DamldocOptions{..} docData = do
|
||||
case do_outputFormat of
|
||||
OutputJson ->
|
||||
write do_outputPath $ T.decodeUtf8 . LBS.toStrict $ AP.encodePretty' jsonConf docData
|
||||
OutputHoogle ->
|
||||
write do_outputPath . T.concat $ map renderSimpleHoogle docData
|
||||
OutputDocs format -> do
|
||||
let renderOptions = RenderOptions
|
||||
{ ro_mode =
|
||||
@ -114,5 +117,9 @@ renderDocData DamldocOptions{..} docData = do
|
||||
, ro_title = do_docTitle
|
||||
, ro_template = templateM
|
||||
, ro_indexTemplate = indexTemplateM
|
||||
, ro_hoogleTemplate = hoogleTemplateM
|
||||
, ro_baseURL = do_baseURL
|
||||
, ro_hooglePath = do_hooglePath
|
||||
, ro_anchorPath = do_anchorPath
|
||||
}
|
||||
renderDocs renderOptions docData
|
||||
|
@ -22,8 +22,8 @@ import DA.Daml.Doc.Render.Hoogle
|
||||
import DA.Daml.Doc.Render.Output
|
||||
import DA.Daml.Doc.Types
|
||||
|
||||
import Control.Monad.Extra
|
||||
import Data.Maybe
|
||||
import Data.List.Extra
|
||||
import Data.Foldable
|
||||
import System.Directory
|
||||
import System.FilePath
|
||||
@ -31,7 +31,7 @@ import System.IO
|
||||
import System.Exit
|
||||
|
||||
import qualified CMarkGFM as GFM
|
||||
import qualified Data.Aeson.Types as A
|
||||
import qualified Data.Aeson as A
|
||||
import qualified Data.Aeson.Encode.Pretty as AP
|
||||
import qualified Data.Text as T
|
||||
import qualified Data.Text.Lazy as TL
|
||||
@ -45,13 +45,14 @@ jsonConf :: AP.Config
|
||||
jsonConf = AP.Config (AP.Spaces 2) (AP.keyOrder ["id"]) AP.Generic True
|
||||
|
||||
renderDocs :: RenderOptions -> [ModuleDoc] -> IO ()
|
||||
renderDocs RenderOptions{..} mods = do
|
||||
renderDocs ro@RenderOptions{..} mods = do
|
||||
let (formatter, postProcessing) =
|
||||
case ro_format of
|
||||
Rst -> (renderRst, id)
|
||||
Markdown -> (renderMd, id)
|
||||
Html -> (renderMd, GFM.commonmarkToHtml [GFM.optUnsafe] [GFM.extTable])
|
||||
templateText = fromMaybe (defaultTemplate ro_format) ro_template
|
||||
renderMap = Map.fromList [(md_name mod, renderModule mod) | mod <- mods]
|
||||
|
||||
template <- compileTemplate "template" templateText
|
||||
|
||||
@ -59,15 +60,13 @@ renderDocs RenderOptions{..} mods = do
|
||||
RenderToFile path -> do
|
||||
BS.writeFile path
|
||||
. T.encodeUtf8
|
||||
. renderTemplate template
|
||||
(fromMaybe "Package Docs" ro_title)
|
||||
. renderTemplate ro template
|
||||
. postProcessing
|
||||
. renderPage formatter
|
||||
$ mconcatMap renderModule mods
|
||||
$ fold renderMap
|
||||
|
||||
RenderToFolder path -> do
|
||||
let renderMap = Map.fromList
|
||||
[(md_name mod, renderModule mod) | mod <- mods]
|
||||
let
|
||||
(outputIndex, outputMap) = renderFolder formatter renderMap
|
||||
extension =
|
||||
case ro_format of
|
||||
@ -76,16 +75,12 @@ renderDocs RenderOptions{..} mods = do
|
||||
Html -> "html"
|
||||
|
||||
outputPath mod = path </> moduleNameToFileName mod <.> extension
|
||||
pageTitle mod = T.concat
|
||||
[ maybe "" (<> " - ") ro_title
|
||||
, "Module "
|
||||
, unModulename mod ]
|
||||
|
||||
createDirectoryIfMissing True path
|
||||
for_ (Map.toList outputMap) $ \ (mod, renderedOutput) -> do
|
||||
BS.writeFile (outputPath mod)
|
||||
. T.encodeUtf8
|
||||
. renderTemplate template (pageTitle mod)
|
||||
. renderTemplate ro template
|
||||
. postProcessing
|
||||
$ renderedOutput
|
||||
|
||||
@ -94,10 +89,23 @@ renderDocs RenderOptions{..} mods = do
|
||||
|
||||
BS.writeFile (path </> "index" <.> extension)
|
||||
. T.encodeUtf8
|
||||
. renderTemplate indexTemplate (fromMaybe "index" ro_title)
|
||||
. renderTemplate ro indexTemplate
|
||||
. postProcessing
|
||||
$ outputIndex
|
||||
|
||||
let anchorTable = buildAnchorTable ro renderMap
|
||||
whenJust ro_anchorPath $ \anchorPath -> do
|
||||
A.encodeFile anchorPath anchorTable
|
||||
whenJust ro_hooglePath $ \hooglePath -> do
|
||||
let he = HoogleEnv { he_anchorTable = anchorTable }
|
||||
hoogleTemplate <- compileTemplate "hoogle template"
|
||||
(fromMaybe defaultHoogleTemplate ro_hoogleTemplate)
|
||||
BS.writeFile hooglePath
|
||||
. T.encodeUtf8
|
||||
. renderTemplate ro hoogleTemplate
|
||||
. T.concat
|
||||
$ map (renderSimpleHoogle he) mods
|
||||
|
||||
compileTemplate :: T.Text -> T.Text -> IO M.Template
|
||||
compileTemplate templateName templateText =
|
||||
case M.compileMustacheText "daml docs template" templateText of
|
||||
@ -107,16 +115,29 @@ compileTemplate templateName templateText =
|
||||
exitFailure
|
||||
|
||||
renderTemplate ::
|
||||
M.Template -- ^ template
|
||||
-> T.Text -- ^ page title
|
||||
RenderOptions
|
||||
-> M.Template -- ^ template
|
||||
-> T.Text -- ^ page body
|
||||
-> T.Text
|
||||
renderTemplate template pageTitle pageBody =
|
||||
renderTemplate RenderOptions{..} template pageBody =
|
||||
TL.toStrict . M.renderMustache template . A.object $
|
||||
[ "title" A..= pageTitle
|
||||
[ "base-url" A..= fromMaybe "" ro_baseURL
|
||||
, "title" A..= fromMaybe "" ro_title
|
||||
, "body" A..= pageBody
|
||||
]
|
||||
|
||||
defaultHoogleTemplate :: T.Text
|
||||
defaultHoogleTemplate = T.unlines
|
||||
[ "-- Hoogle database generated by damlc."
|
||||
, "-- See Hoogle, http://www.haskell.org/hoogle/"
|
||||
, ""
|
||||
, "@url {{{base-url}}}"
|
||||
, "@package {{package-name}}" -- TODO
|
||||
, "@version {{package-version}}" -- TODO
|
||||
, ""
|
||||
, "{{{body}}}"
|
||||
]
|
||||
|
||||
defaultTemplate :: RenderFormat -> T.Text
|
||||
defaultTemplate = \case
|
||||
Html -> defaultTemplateHtml
|
||||
|
@ -3,15 +3,21 @@
|
||||
|
||||
|
||||
module DA.Daml.Doc.Render.Hoogle
|
||||
( renderSimpleHoogle
|
||||
( HoogleEnv (..)
|
||||
, renderSimpleHoogle
|
||||
) where
|
||||
|
||||
import DA.Daml.Doc.Types
|
||||
import DA.Daml.Doc.Render.Util
|
||||
|
||||
import Data.Maybe
|
||||
import qualified Data.HashMap.Strict as HMS
|
||||
import qualified Data.Text as T
|
||||
|
||||
newtype HoogleEnv = HoogleEnv
|
||||
{ he_anchorTable :: HMS.HashMap Anchor T.Text
|
||||
}
|
||||
|
||||
-- | Convert a markdown comment into hoogle text.
|
||||
hooglify :: Maybe DocText -> [T.Text]
|
||||
hooglify Nothing = []
|
||||
@ -21,46 +27,46 @@ hooglify (Just md) =
|
||||
(x:xs) -> ("-- | " <> x)
|
||||
: map ("-- " <>) xs
|
||||
|
||||
urlTag :: Maybe Anchor -> T.Text
|
||||
urlTag Nothing = ""
|
||||
urlTag (Just (Anchor t)) = "@url https://docs.daml.com/daml/stdlib/index.html#" <> t
|
||||
-- ^ TODO(sofia): This needs a map of anchors to final module names / filenames.
|
||||
-- Or maybe there is a sphinx setting/plugin to create anchor-based redirects for us...
|
||||
urlTag :: HoogleEnv -> Maybe Anchor -> T.Text
|
||||
urlTag env anchorM = fromMaybe "" $ do
|
||||
anchor <- anchorM
|
||||
url <- HMS.lookup anchor (he_anchorTable env)
|
||||
pure ("@url " <> url)
|
||||
|
||||
renderSimpleHoogle :: ModuleDoc -> T.Text
|
||||
renderSimpleHoogle ModuleDoc{..}
|
||||
renderSimpleHoogle :: HoogleEnv -> ModuleDoc -> T.Text
|
||||
renderSimpleHoogle _env ModuleDoc{..}
|
||||
| null md_classes && null md_adts &&
|
||||
null md_functions && isNothing md_descr = T.empty
|
||||
renderSimpleHoogle ModuleDoc{..} = T.unlines . concat $
|
||||
renderSimpleHoogle env ModuleDoc{..} = T.unlines . concat $
|
||||
[ hooglify md_descr
|
||||
, [ urlTag md_anchor
|
||||
, [ urlTag env md_anchor
|
||||
, "module " <> unModulename md_name
|
||||
, "" ]
|
||||
, concatMap adt2hoogle md_adts
|
||||
, concatMap cls2hoogle md_classes
|
||||
, concatMap fct2hoogle md_functions
|
||||
, concatMap (adt2hoogle env) md_adts
|
||||
, concatMap (cls2hoogle env) md_classes
|
||||
, concatMap (fct2hoogle env) md_functions
|
||||
]
|
||||
|
||||
adt2hoogle :: ADTDoc -> [T.Text]
|
||||
adt2hoogle TypeSynDoc{..} = concat
|
||||
adt2hoogle :: HoogleEnv -> ADTDoc -> [T.Text]
|
||||
adt2hoogle env TypeSynDoc{..} = concat
|
||||
[ hooglify ad_descr
|
||||
, [ urlTag ad_anchor
|
||||
, [ urlTag env ad_anchor
|
||||
, T.unwords ("type" : wrapOp (unTypename ad_name) :
|
||||
ad_args ++ ["=", type2hoogle ad_rhs])
|
||||
, "" ]
|
||||
]
|
||||
adt2hoogle ADTDoc{..} = concat
|
||||
adt2hoogle env ADTDoc{..} = concat
|
||||
[ hooglify ad_descr
|
||||
, [ urlTag ad_anchor
|
||||
, [ urlTag env ad_anchor
|
||||
, T.unwords ("data" : wrapOp (unTypename ad_name) : ad_args)
|
||||
, "" ]
|
||||
, concatMap (adtConstr2hoogle ad_name) ad_constrs
|
||||
, concatMap (adtConstr2hoogle env ad_name) ad_constrs
|
||||
]
|
||||
|
||||
adtConstr2hoogle :: Typename -> ADTConstr -> [T.Text]
|
||||
adtConstr2hoogle typename PrefixC{..} = concat
|
||||
adtConstr2hoogle :: HoogleEnv -> Typename -> ADTConstr -> [T.Text]
|
||||
adtConstr2hoogle env typename PrefixC{..} = concat
|
||||
[ hooglify ac_descr
|
||||
, [ urlTag ac_anchor
|
||||
, [ urlTag env ac_anchor
|
||||
, T.unwords
|
||||
[ wrapOp (unTypename ac_name)
|
||||
, "::"
|
||||
@ -68,9 +74,9 @@ adtConstr2hoogle typename PrefixC{..} = concat
|
||||
]
|
||||
, "" ]
|
||||
]
|
||||
adtConstr2hoogle typename RecordC{..} = concat
|
||||
adtConstr2hoogle env typename RecordC{..} = concat
|
||||
[ hooglify ac_descr
|
||||
, [ urlTag ac_anchor
|
||||
, [ urlTag env ac_anchor
|
||||
, T.unwords
|
||||
[ wrapOp (unTypename ac_name)
|
||||
, "::"
|
||||
@ -95,22 +101,22 @@ fieldDoc2hoogle typename FieldDoc{..} = concat
|
||||
]
|
||||
|
||||
|
||||
cls2hoogle :: ClassDoc -> [T.Text]
|
||||
cls2hoogle ClassDoc{..} = concat
|
||||
cls2hoogle :: HoogleEnv -> ClassDoc -> [T.Text]
|
||||
cls2hoogle env ClassDoc{..} = concat
|
||||
[ hooglify cl_descr
|
||||
, [ urlTag cl_anchor
|
||||
, [ urlTag env cl_anchor
|
||||
, T.unwords $ ["class"]
|
||||
++ maybe [] ((:["=>"]) . type2hoogle) cl_super
|
||||
++ wrapOp (unTypename cl_name) : cl_args
|
||||
, "" ]
|
||||
, concatMap classMethod2hoogle cl_methods
|
||||
, concatMap (classMethod2hoogle env) cl_methods
|
||||
]
|
||||
|
||||
classMethod2hoogle :: ClassMethodDoc -> [T.Text]
|
||||
classMethod2hoogle ClassMethodDoc{..} | cm_isDefault = [] -- hide default methods from hoogle search
|
||||
classMethod2hoogle ClassMethodDoc{..} = concat
|
||||
classMethod2hoogle :: HoogleEnv -> ClassMethodDoc -> [T.Text]
|
||||
classMethod2hoogle _env ClassMethodDoc{..} | cm_isDefault = [] -- hide default methods from hoogle search
|
||||
classMethod2hoogle env ClassMethodDoc{..} = concat
|
||||
[ hooglify cm_descr
|
||||
, [ urlTag cm_anchor
|
||||
, [ urlTag env cm_anchor
|
||||
, T.unwords . concat $
|
||||
[ [wrapOp (unFieldname cm_name), "::"]
|
||||
, maybe [] ((:["=>"]) . type2hoogle) cm_globalContext
|
||||
@ -119,10 +125,10 @@ classMethod2hoogle ClassMethodDoc{..} = concat
|
||||
, "" ]
|
||||
]
|
||||
|
||||
fct2hoogle :: FunctionDoc -> [T.Text]
|
||||
fct2hoogle FunctionDoc{..} = concat
|
||||
fct2hoogle :: HoogleEnv -> FunctionDoc -> [T.Text]
|
||||
fct2hoogle env FunctionDoc{..} = concat
|
||||
[ hooglify fct_descr
|
||||
, [ urlTag fct_anchor
|
||||
, [ urlTag env fct_anchor
|
||||
, T.unwords . concat $
|
||||
[ [wrapOp (unFieldname fct_name), "::"]
|
||||
, maybe [] ((:["=>"]) . type2hoogle) fct_context
|
||||
|
@ -9,12 +9,14 @@ module DA.Daml.Doc.Render.Monoid
|
||||
) where
|
||||
|
||||
import DA.Daml.Doc.Types
|
||||
import DA.Daml.Doc.Render.Types
|
||||
import Control.Monad
|
||||
import Data.Foldable
|
||||
import Data.Maybe
|
||||
import Data.List.Extra
|
||||
import System.FilePath
|
||||
import qualified Data.Map.Strict as Map
|
||||
import qualified Data.HashMap.Strict as HMS
|
||||
import qualified Data.Set as Set
|
||||
import qualified Data.Text as T
|
||||
import qualified Network.URI as URI
|
||||
@ -173,3 +175,38 @@ renderFolder formatter fileMap =
|
||||
moduleNameToFileName :: Modulename -> FilePath
|
||||
moduleNameToFileName =
|
||||
T.unpack . T.replace "." "-" . unModulename
|
||||
|
||||
buildAnchorTable :: RenderOptions -> Map.Map Modulename RenderOut -> HMS.HashMap Anchor T.Text
|
||||
buildAnchorTable RenderOptions{..} outputs
|
||||
| Just baseURL <- ro_baseURL
|
||||
= HMS.fromList
|
||||
[ (anchor, buildURL baseURL moduleName anchor)
|
||||
| (moduleName, output) <- Map.toList outputs
|
||||
, anchor <- Set.toList (getRenderAnchors output)
|
||||
]
|
||||
where
|
||||
stripTrailingSlash :: T.Text -> T.Text
|
||||
stripTrailingSlash x = fromMaybe x (T.stripSuffix "/" x)
|
||||
|
||||
buildURL :: T.Text -> Modulename -> Anchor -> T.Text
|
||||
buildURL = case ro_mode of
|
||||
RenderToFile _ -> buildFileURL
|
||||
RenderToFolder _ -> buildFolderURL
|
||||
|
||||
buildFileURL :: T.Text -> Modulename -> Anchor -> T.Text
|
||||
buildFileURL baseURL _ anchor = T.concat
|
||||
[ baseURL
|
||||
, "#"
|
||||
, unAnchor anchor
|
||||
]
|
||||
|
||||
buildFolderURL :: T.Text -> Modulename -> Anchor -> T.Text
|
||||
buildFolderURL baseURL moduleName anchor = T.concat
|
||||
[ stripTrailingSlash baseURL
|
||||
, "/"
|
||||
, T.pack (moduleNameToFileName moduleName <.> "html")
|
||||
, "#"
|
||||
, unAnchor anchor
|
||||
]
|
||||
|
||||
buildAnchorTable _ _ = HMS.empty
|
||||
|
@ -24,4 +24,8 @@ data RenderOptions = RenderOptions
|
||||
, ro_title :: Maybe T.Text -- ^ title of rendered documentation
|
||||
, ro_template :: Maybe T.Text -- ^ renderer template
|
||||
, ro_indexTemplate :: Maybe T.Text -- ^ renderer template for index
|
||||
, ro_hoogleTemplate :: Maybe T.Text -- ^ renderer template for hoogle database
|
||||
, ro_baseURL :: Maybe T.Text -- ^ base URL for generated documentation
|
||||
, ro_hooglePath :: Maybe FilePath -- ^ path to output hoogle database
|
||||
, ro_anchorPath :: Maybe FilePath -- ^ path to output anchor table
|
||||
}
|
||||
|
@ -80,7 +80,7 @@ data Reference = Reference
|
||||
|
||||
-- | Anchors are URL-safe (and RST-safe!) ids into the docs.
|
||||
newtype Anchor = Anchor { unAnchor :: Text }
|
||||
deriving newtype (Eq, Ord, Show, ToJSON, FromJSON, IsString)
|
||||
deriving newtype (Eq, Ord, Show, ToJSON, ToJSONKey, FromJSON, IsString, Hashable)
|
||||
|
||||
------------------------------------------------------------
|
||||
-- | Documentation data for a module
|
||||
|
@ -33,6 +33,7 @@ documentation numProcessors = Damldoc
|
||||
<*> optOutputFormat
|
||||
<*> optTemplate
|
||||
<*> optIndexTemplate
|
||||
<*> optHoogleTemplate
|
||||
<*> optOmitEmpty
|
||||
<*> optDataOnly
|
||||
<*> optNoAnnot
|
||||
@ -42,6 +43,9 @@ documentation numProcessors = Damldoc
|
||||
<*> optDropOrphanInstances
|
||||
<*> optCombine
|
||||
<*> optExtractOptions
|
||||
<*> optBaseURL
|
||||
<*> optHooglePath
|
||||
<*> optAnchorPath
|
||||
<*> argMainFiles
|
||||
where
|
||||
optInputFormat :: Parser InputFormat
|
||||
@ -67,6 +71,27 @@ documentation numProcessors = Damldoc
|
||||
<> long "output"
|
||||
<> short 'o'
|
||||
|
||||
optBaseURL :: Parser (Maybe T.Text)
|
||||
optBaseURL =
|
||||
optional . fmap T.pack . option str
|
||||
$ metavar "URL"
|
||||
<> help "Base URL for generated documentation."
|
||||
<> long "base-url"
|
||||
|
||||
optHooglePath :: Parser (Maybe FilePath)
|
||||
optHooglePath =
|
||||
optional . option str
|
||||
$ metavar "PATH"
|
||||
<> help "Path to output hoogle database."
|
||||
<> long "output-hoogle"
|
||||
|
||||
optAnchorPath :: Parser (Maybe FilePath)
|
||||
optAnchorPath =
|
||||
optional . option str
|
||||
$ metavar "PATH"
|
||||
<> help "Path to output anchor table."
|
||||
<> long "output-anchor"
|
||||
|
||||
optTemplate :: Parser (Maybe FilePath)
|
||||
optTemplate =
|
||||
optional . option str
|
||||
@ -82,6 +107,13 @@ documentation numProcessors = Damldoc
|
||||
<> help "Path to mustache template for index, when rendering to a folder. The variable 'body' in the template is substituted with a module index."
|
||||
<> long "index-template"
|
||||
|
||||
optHoogleTemplate :: Parser (Maybe FilePath)
|
||||
optHoogleTemplate =
|
||||
optional . option str
|
||||
$ metavar "FILE"
|
||||
<> help "Path to mustache template for hoogle database."
|
||||
<> long "hoogle-template"
|
||||
|
||||
argMainFiles :: Parser [FilePath]
|
||||
argMainFiles = some $ argument str $ metavar "FILE..."
|
||||
<> help "Main file(s) (*.daml) whose contents are read"
|
||||
@ -102,9 +134,8 @@ documentation numProcessors = Damldoc
|
||||
"md" -> Right (OutputDocs Markdown)
|
||||
"markdown" -> Right (OutputDocs Markdown)
|
||||
"html" -> Right (OutputDocs Html)
|
||||
"hoogle" -> Right OutputHoogle
|
||||
"json" -> Right OutputJson
|
||||
_ -> Left "Unknown output format. Expected rst, md, markdown, html, hoogle, or json."
|
||||
_ -> Left "Unknown output format. Expected rst, md, markdown, html, or json."
|
||||
|
||||
optOmitEmpty :: Parser Bool
|
||||
optOmitEmpty = switch
|
||||
@ -199,6 +230,7 @@ data CmdArgs = Damldoc
|
||||
, cOutputFormat :: OutputFormat
|
||||
, cTemplate :: Maybe FilePath
|
||||
, cIndexTemplate :: Maybe FilePath
|
||||
, cHoogleTemplate :: Maybe FilePath
|
||||
, cOmitEmpty :: Bool
|
||||
, cDataOnly :: Bool
|
||||
, cNoAnnot :: Bool
|
||||
@ -208,6 +240,9 @@ data CmdArgs = Damldoc
|
||||
, cDropOrphanInstances :: Bool
|
||||
, cCombine :: Bool
|
||||
, cExtractOptions :: ExtractOptions
|
||||
, cBaseURL :: Maybe T.Text
|
||||
, cHooglePath :: Maybe FilePath
|
||||
, cAnchorPath :: Maybe FilePath
|
||||
, cMainFiles :: [FilePath]
|
||||
} deriving (Show)
|
||||
|
||||
@ -227,10 +262,14 @@ exec Damldoc{..} = do
|
||||
, do_inputFiles = map toNormalizedFilePath' cMainFiles
|
||||
, do_docTemplate = cTemplate
|
||||
, do_docIndexTemplate = cIndexTemplate
|
||||
, do_docHoogleTemplate = cHoogleTemplate
|
||||
, do_transformOptions = transformOptions
|
||||
, do_docTitle = T.pack . unitIdString <$> optUnitId cOptions
|
||||
, do_combine = cCombine
|
||||
, do_extractOptions = cExtractOptions
|
||||
, do_baseURL = cBaseURL
|
||||
, do_hooglePath = cHooglePath
|
||||
, do_anchorPath = cAnchorPath
|
||||
}
|
||||
|
||||
where
|
||||
|
@ -261,7 +261,7 @@ genrule(
|
||||
genrule(
|
||||
name = "sources",
|
||||
srcs = glob(["source/**"]) + [
|
||||
"//compiler/damlc:daml-base-rst-docs",
|
||||
"//compiler/damlc:daml-base-rst.tar.gz",
|
||||
"//triggers/daml:daml-trigger-rst-docs",
|
||||
"//daml-script/daml:daml-script-rst-docs",
|
||||
"//ledger-api/grpc-definitions:docs",
|
||||
@ -274,7 +274,7 @@ genrule(
|
||||
|
||||
# Copy in Stdlib
|
||||
mkdir -p source/daml/stdlib
|
||||
tar xf $(location //compiler/damlc:daml-base-rst-docs) \
|
||||
tar xf $(location //compiler/damlc:daml-base-rst.tar.gz) \
|
||||
--strip-components 1 \
|
||||
-C source/daml/stdlib
|
||||
|
||||
@ -354,8 +354,7 @@ genrule(
|
||||
]) + [
|
||||
":sources",
|
||||
":theme",
|
||||
"//compiler/damlc:daml-base-rst-docs",
|
||||
"//compiler/damlc:daml-base-hoogle-docs",
|
||||
"//compiler/damlc:daml-base-hoogle.txt",
|
||||
"//language-support/java:javadoc",
|
||||
"//language-support/ts/daml-react:docs",
|
||||
"//language-support/ts/daml-ledger:docs",
|
||||
@ -417,7 +416,7 @@ genrule(
|
||||
|
||||
# Copy in hoogle DB
|
||||
mkdir -p html/hoogle_db
|
||||
cp -rL ../$(location //compiler/damlc:daml-base-hoogle-docs) html/hoogle_db/base.txt
|
||||
cp -rL ../$(location //compiler/damlc:daml-base-hoogle.txt) html/hoogle_db/base.txt
|
||||
|
||||
tar c html \
|
||||
--owner=0 --group=0 --numeric-owner --mtime=2000-01-01\ 00:00Z --sort=name \
|
||||
|
@ -45,7 +45,7 @@ do
|
||||
fi
|
||||
if [ "$arg" = "--gen" ]; then
|
||||
# Hoogle
|
||||
bazel build //compiler/damlc:daml-base-hoogle-docs
|
||||
bazel build //compiler/damlc:daml-base-hoogle.txt
|
||||
mkdir -p $BUILD_DIR/gen/hoogle_db
|
||||
cp -L ../../bazel-bin/compiler/damlc/daml-base-hoogle.txt $BUILD_DIR/gen/hoogle_db/base.txt
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user