Dhall.Docs.Core

Contains all the functions that generate documentation

We should always try to do as little work as possible in an IO context. To do so, just wrap your function in IO if you need to do I/O operations, and make pure functions receive that IO result as an input

Core functionality

generateDocs

Arguments

:: Path Abs Dir

Input directory

-> Path Abs Dir

Link to be created to the generated documentation

-> Maybe Text

Base import URL

-> Text

Package name, used in some HTML titles

-> CharacterSet

Output encoding

-> IO ()

Generate all of the docs for a package. This function does all the `IO ()` related tasks to call generateDocsPure

generateDocsPure

Arguments

:: Maybe Text

Base import URL

-> Text

Package name

-> CharacterSet

Output encoding

-> [(Path Rel File, ByteString)]

(Input file, contents)

-> GeneratedDocs [(Path Rel File, Text)]

Generates all the documentation of dhall package in a pure way i.e. without an IO context. This let you generate documentation from a list of dhall-files without saving them to the filesystem.

If you want the IO version of this function, check generateDocs

data GeneratedDocs a

The result of the doc-generator pure component

Constructors

GeneratedDocs [DocsGenWarning] a

Instances

Monad GeneratedDocs

Defined in Dhall.Docs.Core

Methods

(>>=) :: GeneratedDocs a -> (a -> GeneratedDocs b) -> GeneratedDocs b

(>>) :: GeneratedDocs a -> GeneratedDocs b -> GeneratedDocs b

return :: a -> GeneratedDocs a

Functor GeneratedDocs

Defined in Dhall.Docs.Core

Methods

fmap :: (a -> b) -> GeneratedDocs a -> GeneratedDocs b

(<$) :: a -> GeneratedDocs b -> GeneratedDocs a

Applicative GeneratedDocs

Defined in Dhall.Docs.Core

Methods

pure :: a -> GeneratedDocs a

(<*>) :: GeneratedDocs (a -> b) -> GeneratedDocs a -> GeneratedDocs b

liftA2 :: (a -> b -> c) -> GeneratedDocs a -> GeneratedDocs b -> GeneratedDocs c

(*>) :: GeneratedDocs a -> GeneratedDocs b -> GeneratedDocs b

(<*) :: GeneratedDocs a -> GeneratedDocs b -> GeneratedDocs a

Show a => Show (GeneratedDocs a)

Defined in Dhall.Docs.Core

Methods

showsPrec :: Int -> GeneratedDocs a -> ShowS

show :: GeneratedDocs a -> String

showList :: [GeneratedDocs a] -> ShowS

Comment parsing

parseComments :: String -> Text -> [DhallComment 'RawComment]

Parse all comments in a text fragment

data CommentParseError

Constructors

MissingNewlineOnBlockComment

BadSingleLineCommentsAlignment

BadPrefixesOnSingleLineComments

SeveralSubseqDhallDocsComments

Instances

Show CommentParseError

Defined in Dhall.Docs.Comment

Methods

showsPrec :: Int -> CommentParseError -> ShowS

show :: CommentParseError -> String

showList :: [CommentParseError] -> ShowS

data DhallDocsText

Extracted text from a valid dhall-docs comment

Instances

Show DhallDocsText

Defined in Dhall.Docs.Comment

Methods

showsPrec :: Int -> DhallDocsText -> ShowS

show :: DhallDocsText -> String

showList :: [DhallDocsText] -> ShowS

parseSingleDhallDocsComment :: String -> Text -> Maybe (Either [CommentParseError] DhallDocsText)

Returns Nothing when DhallDocsComment was parsed or no error was detected

unDhallDocsText :: DhallDocsText -> Text