diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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` diff --git a/dhall-docs.cabal b/dhall-docs.cabal --- a/dhall-docs.cabal +++ b/dhall-docs.cabal @@ -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 diff --git a/src/Dhall/Docs/Core.hs b/src/Dhall/Docs/Core.hs --- a/src/Dhall/Docs/Core.hs +++ b/src/Dhall/Docs/Core.hs @@ -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) diff --git a/src/Dhall/Docs/Html.hs b/src/Dhall/Docs/Html.hs --- a/src/Dhall/Docs/Html.hs +++ b/src/Dhall/Docs/Html.hs @@ -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 diff --git a/tasty/data/golden/AsText.dhall.html b/tasty/data/golden/AsText.dhall.html new file mode 100644 --- /dev/null +++ b/tasty/data/golden/AsText.dhall.html @@ -0,0 +1,43 @@ + + + +/AsText.dhall + + + + + + +
+ +

test-package

+
+
+Switch Light/Dark Mode +
+
+

+/ +test-package +/ +AsText.dhall +

+ + +Copy path to clipboard + + +
+
+
+

Source

+
+
+./Plain.txt as Text
+

+
+
+
+ + diff --git a/tasty/data/golden/Plain.txt.html b/tasty/data/golden/Plain.txt.html new file mode 100644 --- /dev/null +++ b/tasty/data/golden/Plain.txt.html @@ -0,0 +1,41 @@ + + + +/Plain.txt + + + + + + +
+ +

test-package

+
+
+Switch Light/Dark Mode +
+
+

+/ +test-package +/ +Plain.txt +

+ + +Copy path to clipboard + + +
+
+
+

Source

+
+
A plain text file that is imported `as Text` by `./AsText.dhall`

+
+
+
+ + diff --git a/tasty/data/golden/index.html b/tasty/data/golden/index.html --- a/tasty/data/golden/index.html +++ b/tasty/data/golden/index.html @@ -33,6 +33,9 @@

Exported files: