dhall-docs 1.0.9 → 1.0.10

raw patch · 9 files changed

+220/−55 lines, 9 filesdep ~mtldep ~transformersdep ~turtlePVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependency ranges changed: mtl, transformers, turtle

API changes (from Hackage documentation)

Files

• CHANGELOG.md +4/−0
• dhall-docs.cabal +3/−1
• src/Dhall/Docs/Core.hs +98/−54
• src/Dhall/Docs/Html.hs +23/−0
• tasty/data/golden/AsText.dhall.html +43/−0
• tasty/data/golden/Plain.txt.html +41/−0
• tasty/data/golden/index.html +6/−0
• tasty/data/package/AsText.dhall +1/−0
• tasty/data/package/Plain.txt +1/−0

@@ -1,3 +1,7 @@+1.0.10++* [Index non-`.dhall` files](https://github.com/dhall-lang/dhall-haskell/pull/2407)+ 1.0.9  * Build against `dhall-1.41`

@@ -1,5 +1,5 @@ Name: dhall-docs-Version: 1.0.9+Version: 1.0.10 Cabal-Version: >=1.10 Build-Type: Simple License: BSD3@@ -22,11 +22,13 @@ Extra-Source-Files:     CHANGELOG.md     README.md+    tasty/data/package/*.txt     tasty/data/package/*.dhall     tasty/data/package/a/*.dhall     tasty/data/package/a/b/*.dhall     tasty/data/package/a/b/c/*.dhall     tasty/data/package/deep/nested/folder/*.dhall+    tasty/data/golden/*.txt.html     tasty/data/golden/*.dhall.html     tasty/data/golden/a/*.dhall.html     tasty/data/golden/a/b/*.dhall.html

@@ -147,30 +147,42 @@ -- | Represents a Dhall file that can be rendered as documentation. --   If you'd like to improve or add features to a .dhall documentation page, --   add that extra information here.-data DhallFile = DhallFile-    { path :: Path Rel File             -- ^ Path of the file-    , contents :: Text                  -- ^ File contents-    , expr :: Expr Src Import           -- ^ Parsed AST from 'contents'-    , mType :: Maybe (Expr Void Import) -- ^ Type of the parsed expression,-                                        --   extracted from the source code-    , examples :: [Expr Void Import]    -- ^ Examples extracted from assertions-                                        --   in the file-    , fileComments :: FileComments+data RenderedFile = RenderedFile+    { path :: Path Rel File+      -- ^ Path of the file+    , contents :: Text+      -- ^ File contents+    , fileType :: FileType+      -- ^ This corresponds to the import mode (e.g. @as Text@)     } deriving (Show) +data FileType+    = DhallFile+        { expr :: Expr Src Import+          -- ^ Parsed AST from 'contents'+        , mType :: Maybe (Expr Void Import)+          -- ^ Type of the parsed expression, extracted from the source code+        , examples :: [Expr Void Import]+          -- ^ Examples extracted from assertions in the file+        , fileComments :: FileComments+        }+    | TextFile+    deriving (Show)+ {-| Takes a list of files paths with their contents and returns the list of-    valid `DhallFile`s.+    valid `RenderedFile`s.      Returned files contains all the information to be used on `Html ()`     generation.      The result is sorted by `path` -}-getAllDhallFiles :: [(Path Rel File, ByteString)] -> GeneratedDocs [DhallFile]-getAllDhallFiles = fmap Maybe.catMaybes . mapM toDhallFile . foldr validFiles [] . filter hasDhallExtension+getAllRenderedFiles :: [(Path Rel File, ByteString)] -> GeneratedDocs [RenderedFile]+getAllRenderedFiles =+    fmap Maybe.catMaybes . mapM toRenderedFile . foldr validFiles []   where-    hasDhallExtension :: (Path Rel File, a) -> Bool-    hasDhallExtension (absFile, _) = case Path.splitExtension absFile of+    hasDhallExtension :: Path Rel File -> Bool+    hasDhallExtension absFile = case Path.splitExtension absFile of         Nothing -> False         Just (_, ext) -> ext == ".dhall" @@ -179,8 +191,9 @@         Left _ -> xs         Right textContent -> (relFile, textContent) : xs -    toDhallFile :: (Path Rel File, Text) -> GeneratedDocs (Maybe DhallFile)-    toDhallFile (relFile, contents) =+    toRenderedFile+        :: (Path Rel File, Text) -> GeneratedDocs (Maybe RenderedFile)+    toRenderedFile (relFile, contents) =         case exprAndHeaderFromText (Path.fromRelFile relFile) contents of             Right (Header header, expr) -> do                 let denoted = denote expr :: Expr Void Import@@ -193,17 +206,27 @@                             return Nothing                         Just (Right c) -> return $ Just c -                return $ Just $ DhallFile-                    { expr, contents+                return $ Just $ RenderedFile+                    { contents                     , path = relFile-                    , mType = extractTypeIfInSource denoted-                    , examples = examplesFromAssertions denoted-                    , fileComments = FileComments headerContents+                    , fileType = DhallFile+                        { expr+                        , mType = extractTypeIfInSource denoted+                        , examples = examplesFromAssertions denoted+                        , fileComments = FileComments headerContents+                        }                     }-            Left ParseError{..} -> do+            Left ParseError{..} | hasDhallExtension relFile -> do                 Writer.tell [InvalidDhall unwrap]                 return Nothing +            Left _ -> do+                return $ Just $ RenderedFile+                    { contents+                    , path = relFile+                    , fileType = TextFile+                    }+     bindings :: Expr Void Import -> [Binding Void Import]     bindings expr = case expr of         Let b@Binding{} e ->@@ -288,33 +311,48 @@         "." -> ""         _ -> "../" <> resolveRelativePath (Path.parent currentDir) --- | Generates `Text` from the HTML representation of a `DhallFile`+-- | Generates `Text` from the HTML representation of a `RenderedFile` makeHtml     :: Maybe Text           -- ^ Base import URL     -> Text                 -- ^ Package name     -> CharacterSet         -- ^ Output encoding-    -> DhallFile            -- ^ Parsed header+    -> RenderedFile            -- ^ Parsed header     -> GeneratedDocs Text-makeHtml baseImportUrl packageName characterSet DhallFile {..} = do-    let relativeResourcesPath = resolveRelativePath $ Path.parent path-    let strippedHeader = Maybe.maybe "" unDhallDocsText (headerComment fileComments)-    headerAsHtml <--        case markdownToHtml path strippedHeader of-            Left err -> do-                Writer.tell [InvalidMarkdown err]-                return $ Lucid.toHtml strippedHeader-            Right html -> return html+makeHtml baseImportUrl packageName characterSet RenderedFile{..} = do+    let relativeResourcesPath = resolveRelativePath (Path.parent path) -    let htmlAsText = Text.Lazy.toStrict $ Lucid.renderText $ dhallFileToHtml-            path-            contents-            expr-            examples-            headerAsHtml-            DocParams { relativeResourcesPath, packageName, characterSet, baseImportUrl }+    case fileType of+        DhallFile{..} -> do+            let strippedHeader =+                    Maybe.maybe "" unDhallDocsText (headerComment fileComments) -    return htmlAsText+            headerAsHtml <-+                case markdownToHtml path strippedHeader of+                    Left err -> do+                        Writer.tell [InvalidMarkdown err]+                        return $ Lucid.toHtml strippedHeader+                    Right html -> return html +            let htmlAsText =+                    Text.Lazy.toStrict $ Lucid.renderText $ dhallFileToHtml+                        path+                        contents+                        expr+                        examples+                        headerAsHtml+                        DocParams{ relativeResourcesPath, packageName, characterSet, baseImportUrl }++            return htmlAsText+        TextFile -> do+            let htmlAsText =+                    Text.Lazy.toStrict $ Lucid.renderText $ textFileToHtml+                        path+                        contents+                        DocParams{ relativeResourcesPath, packageName, characterSet, baseImportUrl }++            return htmlAsText++ {-| Create an @index.html@ file on each available folder in the input.      Each @index.html@ lists the files and directories of its directory. Listed@@ -337,16 +375,16 @@     :: Maybe Text     -> Text     -> CharacterSet-    -> [DhallFile]+    -> [RenderedFile]     -> [(Path Rel File, Text)]-createIndexes baseImportUrl packageName characterSet dhallFiles = map toIndex dirToDirsAndFilesMapAssocs+createIndexes baseImportUrl packageName characterSet renderedFiles = map toIndex dirToDirsAndFilesMapAssocs   where     -- Files grouped by their directory-    dirToFilesMap :: Map (Path Rel Dir) [DhallFile]-    dirToFilesMap = Map.unionsWith (<>) $ map toMap $ Data.List.sortBy (compare `on` path) dhallFiles+    dirToFilesMap :: Map (Path Rel Dir) [RenderedFile]+    dirToFilesMap = Map.unionsWith (<>) $ map toMap $ Data.List.sortBy (compare `on` path) renderedFiles       where-        toMap :: DhallFile -> Map (Path Rel Dir) [DhallFile]-        toMap dhallFile = Map.singleton (Path.parent $ path dhallFile) [dhallFile]+        toMap :: RenderedFile -> Map (Path Rel Dir) [RenderedFile]+        toMap renderedFile = Map.singleton (Path.parent $ path renderedFile) [renderedFile]      {-  This is used to compute the list of exported packages on each folder.         We try to compress the folders as much as we can. See `createIndexes`@@ -361,7 +399,7 @@          cons d = Map.insertWith (<>) (Path.parent d) [d] -    dirToDirsAndFilesMapAssocs :: [(Path Rel Dir, ([DhallFile], [Path Rel Dir]))]+    dirToDirsAndFilesMapAssocs :: [(Path Rel Dir, ([RenderedFile], [Path Rel Dir]))]     dirToDirsAndFilesMapAssocs = Map.assocs $         Map.Merge.merge             (Map.Merge.mapMissing onlyFiles)@@ -374,13 +412,19 @@         onlyDirectories _       directories = ([]   , directories)         both            _ files directories = (files, directories) -    toIndex :: (Path Rel Dir, ([DhallFile], [Path Rel Dir])) -> (Path Rel File, Text)+    toIndex :: (Path Rel Dir, ([RenderedFile], [Path Rel Dir])) -> (Path Rel File, Text)     toIndex (indexDir, (files, dirs)) =         (indexDir </> $(Path.mkRelFile "index.html"), Text.Lazy.toStrict $ Lucid.renderText html)       where+        adapt RenderedFile{..} = (stripPrefix (addHtmlExt path), m)+          where+            m = case fileType of+                DhallFile{..} -> mType+                TextFile      -> Nothing+         html = indexToHtml             indexDir-            (map (\DhallFile{..} -> (stripPrefix $ addHtmlExt path, mType)) files)+            (map adapt files)             (map stripPrefix dirs)             DocParams { relativeResourcesPath = resolveRelativePath indexDir, packageName, characterSet, baseImportUrl } @@ -476,7 +520,7 @@   where     go :: GeneratedDocs [(Path Rel File, Text)]     go = do-        dhallFiles <- getAllDhallFiles inputFiles-        htmls <- mapM (makeHtml baseImportUrl packageName characterSet) dhallFiles-        let indexes = createIndexes baseImportUrl packageName characterSet dhallFiles-        return (zip (map (addHtmlExt . path) dhallFiles) htmls <> indexes)+        renderedFiles <- getAllRenderedFiles inputFiles+        htmls <- mapM (makeHtml baseImportUrl packageName characterSet) renderedFiles+        let indexes = createIndexes baseImportUrl packageName characterSet renderedFiles+        return (zip (map (addHtmlExt . path) renderedFiles) htmls <> indexes)

@@ -13,6 +13,7 @@  module Dhall.Docs.Html     ( dhallFileToHtml+    , textFileToHtml     , indexToHtml     , DocParams(..)     ) where@@ -71,6 +72,28 @@                         mapM_ (renderCodeSnippet characterSet AssertionExample) examples                 h3_ "Source"                 div_ [class_ "source-code"] $ renderCodeWithHyperLinks contents expr+  where+    breadcrumb = relPathToBreadcrumb filePath+    htmlTitle = breadCrumbsToText breadcrumb+    clipboardText = fold baseImportUrl <> htmlTitle++-- | Generates an @`Html` ()@ with all the information about a dhall file+textFileToHtml+    :: Path Rel File            -- ^ Source file name, used to extract the title+    -> Text                     -- ^ Contents of the file+    -> DocParams                -- ^ Parameters for the documentation+    -> Html ()+textFileToHtml filePath contents params@DocParams{..} =+    doctypehtml_ $ do+        headContents htmlTitle params+        body_ $ do+            navBar params+            mainContainer $ do+                setPageTitle params NotIndex breadcrumb+                copyToClipboardButton clipboardText+                br_ []+                h3_ "Source"+                div_ [class_ "source-code"] (toHtml contents)   where     breadcrumb = relPathToBreadcrumb filePath     htmlTitle = breadCrumbsToText breadcrumb

@@ -0,0 +1,43 @@+<!DOCTYPE HTML>+<html>+<head>+<title>/AsText.dhall</title>+<link rel="stylesheet" type="text/css" href="index.css">+<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600;700&amp;family=Lato:ital,wght@0,400;0,700;1,400&amp;display=swap">+<script type="text/javascript" src="index.js">+</script>+<meta charset="UTF-8">+</head>+<body>+<div class="nav-bar">+<img class="dhall-icon" src="dhall-icon.svg">+<p class="package-title">test-package</p>+<div class="nav-bar-content-divider">+</div>+<a id="switch-light-dark-mode" class="nav-option">Switch Light/Dark Mode</a>+</div>+<div class="main-container">+<h2 class="doc-title">+<span class="crumb-divider">/</span>+<a href="index.html">test-package</a>+<span class="crumb-divider">/</span>+<span class="title-crumb" href="index.html">AsText.dhall</span>+</h2>+<a class="copy-to-clipboard" data-path="/AsText.dhall">+<i>+<small>Copy path to clipboard</small>+</i>+</a>+<br>+<div class="doc-contents">+</div>+<h3>Source</h3>+<div class="source-code">+<pre>+<a href="./Plain.txt.html">./Plain.txt as Text</a>+<br>+</pre>+</div>+</div>+</body>+</html>

@@ -0,0 +1,41 @@+<!DOCTYPE HTML>+<html>+<head>+<title>/Plain.txt</title>+<link rel="stylesheet" type="text/css" href="index.css">+<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600;700&amp;family=Lato:ital,wght@0,400;0,700;1,400&amp;display=swap">+<script type="text/javascript" src="index.js">+</script>+<meta charset="UTF-8">+</head>+<body>+<div class="nav-bar">+<img class="dhall-icon" src="dhall-icon.svg">+<p class="package-title">test-package</p>+<div class="nav-bar-content-divider">+</div>+<a id="switch-light-dark-mode" class="nav-option">Switch Light/Dark Mode</a>+</div>+<div class="main-container">+<h2 class="doc-title">+<span class="crumb-divider">/</span>+<a href="index.html">test-package</a>+<span class="crumb-divider">/</span>+<span class="title-crumb" href="index.html">Plain.txt</span>+</h2>+<a class="copy-to-clipboard" data-path="/Plain.txt">+<i>+<small>Copy path to clipboard</small>+</i>+</a>+<br>+<div class="doc-contents">+</div>+<h3>Source</h3>+<div class="source-code">+<pre>A plain text file that is imported `as Text` by `./AsText.dhall`<br>+</pre>+</div>+</div>+</body>+</html>

@@ -33,6 +33,9 @@ <h3>Exported files: </h3> <ul> <li>+<a href="AsText.dhall.html">AsText.dhall</a>+</li>+<li> <a href="ImportAsType.dhall.html">ImportAsType.dhall</a> <span class="of-type-token">:</span> <span class="dhall-type source-code">@@ -155,6 +158,9 @@ <pre>∀(A : Type) → ∀(B : Type) → Type<br> </pre> </span>+</li>+<li>+<a href="Plain.txt.html">Plain.txt</a> </li> <li> <a href="RenderTypeIndexesExample.dhall.html">RenderTypeIndexesExample.dhall</a>

@@ -0,0 +1,1 @@+./Plain.txt as Text

@@ -0,0 +1,1 @@+A plain text file that is imported `as Text` by `./AsText.dhall`