diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,14 @@
+1.0.5
+
+* [BUG FIX: Fix index generation](https://github.com/dhall-lang/dhall-haskell/pull/2150)
+ * Indices are now created for intermediate directories without `.dhall` files
+ * `dhall-docs` no longer hangs when the top-level directory has no `.dhall` files
+* [Fix lower bound on `dhall`](https://github.com/dhall-lang/dhall-haskell/pull/2147/)
+* [Allow doctest-0.18](https://github.com/dhall-lang/dhall-haskell/pull/2148)
+* [Allow bytestring-0.11](https://github.com/dhall-lang/dhall-haskell/pull/2144)
+* [Add `README` to tarball](https://github.com/dhall-lang/dhall-haskell/pull/2145)
+* [Remove test dependency on HaXml](https://github.com/dhall-lang/dhall-haskell/pull/2156)
+
1.0.4
* Build against `dhall-1.38.0`, `tasty-1.4`, `tasty-silver-3.2`, and
diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,517 @@
+# `dhall-docs`
+
+For installation or development instructions, see:
+
+* [`dhall-haskell` - `README`](https://github.com/dhall-lang/dhall-haskell/blob/master/README.md)
+
+## Introduction
+
+This `dhall-docs` package provides a command-line utility that takes a dhall package or
+file and outputs an HTML documentation of it.
+
+## Features
+
+`dhall-docs` can analyze your Dhall package (essentially a folder with several
+`.dhall` files) to generate documentation. Specifically:
+
+* Extracts documentation from each file's header comments (see [Comment format](#comment-format)).
+* The generated documentation includes breadcrumbs to aid navigation.
+* Create an index for each folder in your package listing the `.dhall` files
+ in that folder alongside the "exported packages" (the contained folders).
+* Extracts examples from assertions.
+* Extracts the type of each Dhall file from the source code and renders it
+ in the indexes.
+* Renders the source code in each Dhall file's documentation.
+* Jump-to-definition on imports and let-bindings
+
+To see a demo, visit the documentation for the
+[`Dhall Prelude`](https://hydra.dhall-lang.org/job/dhall-haskell/master/prelude-dhall-docs/latest/download/1/docs).
+You can also check the [tests](./tasty/data/package/) folder for further examples
+
+## Usage
+
+The easiest usage is the following:
+
+```bash
+dhall-docs --input ${PACKAGE-FOLDER}
+```
+
+`dhall-docs` will store the documentation in
+`${XDG_DATA_HOME}/dhall-docs/${OUTPUT-HASH}-${PACKAGE-NAME}/`, where:
+
+* `$XDG_DATA_HOME` environment variable comes from the
+ [xdg](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
+ specification. If it is not defined, `dhall-docs` will default to
+ `~/.local/share/`.
+* `OUTPUT-HASH` is the hash of the generated documentation. This is to make the
+ folder [content-addressable](https://es.wikipedia.org/wiki/Content_Addressed_Storage).
+ Also, it avoids overwriting the documentation folder when there was a change in
+ the way it was generated.
+* `PACKAGE-NAME` is the package name of your documentation. By default, it will
+ be the basename of the `--input` folder, but you can override it via
+ `--package-name`.
+
+After generating the documentation, `dhall-docs` will create a symlink to the
+documentation index at `./docs/index.html`. You can customize the location of
+that symlink using `--output-link` flag, like this:
+
+```bash
+dhall-docs --input . --output-link ${OTHER_LINK}
+```
+
+For more information about the tool, check the `--help` flag.
+
+
+## Documenting your packages
+
+Documenting your package is essentially writing comments on your source code,
+although there are some format rules that these need to obey to work
+properly with `dhall-docs`. These rules aid `dhall-docs` in extracting the text
+on the documentation that will be passed to our Markdown preprocessor to finally
+render your documentation in HTML.
+
+You can see examples of writing documentation on the [tests](./tasty/data/package)
+folder.
+
+In every example we used `␣` as an alias to a whitespace character
+
+### Documentation markup language
+
+The markup language of the documentation is [CommonMark], which is a strict
+Markdown flavor. `dhall-docs` uses [`mmark`], a package that parses
+[CommonMark] and transforms it to HTML. This package follows (almost)
+that specification.
+
+### Block comments
+
+Normal block comments in Dhall starts with `{-` and ends with `-}`:
+
+```dhall
+{- foo
+ bar
+ baz
+-}
+```
+
+A `dhall-docs` block comment needs to start with `"{-|"` and a
+newline. The newline can be either `\n` or `\r\n`. This means that the actual
+documentation _must_ starts on the following line.
+
+[CommonMark] supports some features that are sensitive to indentation (e.g.
+[indented-code-blocks]). Indentation on `dhall-docs` block comments is roughly
+the same to [Dhall multi-line strings]: the indentation is determined by the
+longest common whitespace prefix between the lines on the block comment.
+
+In all the following examples:
+
+```dhall
+{-|
+foo
+ bar
+ baz
+-}
+```
+
+```dhall
+ {-|
+foo
+ bar
+ baz
+-}
+```
+
+```dhall
+{-|
+ foo
+ bar
+ baz
+ -}
+```
+
+```dhall
+{-|
+ foo
+ bar
+ baz-}
+```
+
+... `dhall-docs` will extract the contents of the comment, stripping all the
+common leading whitespace from all lines, returning the following text that will
+be passed to our [CommonMark] parser:
+
+```
+foo
+ bar
+ baz
+```
+
+Similar to Dhall multi-line string literals, the `-}` position also affects the
+final indentation, meaning that in the following sample:
+
+```dhall
+{-|
+ foo
+ bar
+-}
+```
+
+The following text will be extracted:
+
+```
+ foo
+ bar
+```
+
+Only spaces and tabs are taken into account in calculating the longest common
+whitespace prefix. Other forms of whitespaces are not considered.
+
+Empty lines are ignored when determining the indentation level but are preserved
+on the extracted text. On the following example:
+
+```dhall
+{-|
+ foo
+
+ bar
+ -}
+```
+
+`dhall-docs` will extract the following text:
+
+```
+foo
+
+bar
+```
+
+Note that a line that only contains trailing whitespace will be taken into
+account when calculating the common indentation. The line between `foo` and `bar`
+on the following example has leading whitespace (two (2) whitespaces):
+
+```dhall
+␣␣{-|
+␣␣␣␣foo
+␣␣
+␣␣␣␣bar -}
+```
+
+meaning that the extracted text will be:
+
+```
+ foo
+
+ bar
+```
+
+If there is no newline between the opening brace of a `dhall-docs` block comment
+(i.e. `{-|`), that comment will be considered invalid: `dhall-docs` will not
+render it on the documentation _and_ a warning will be logged on the console:
+
+```dhall
+ {-| foo
+ bar -}
+```
+
+... although it's a valid Dhall block comment, it's invalid for `dhall-docs`.
+
+To end, if the `|` character isn't immediately after the opening brace,
+`dhall-docs` will ignore the comment without logging on the console. This lets
+you separate your internal block comments from the ones that you want
+`dhall-docs` to output in the final markup.
+
+This is an example of a file documented using block comments:
+
+```dhall
+{-|
+# My awesome package
+
+This is the header of my package
+
+* a list item in **bold**
+ - a sub item in _italic_
+ - a [link](https://example.com)
+ * a `code` quote
+
+
+A new paragraph
+
+ an indented code block
+-}
+let myAwesomeFunction {- this will be ignored on the documentation -}
+ = \(x : Natural) -> x + 1
+
+in
+{
+ {-|
+ foo
+ bar
+ baz
+ -}
+ myAwesomeFunction
+}
+```
+
+### Line comments
+
+Normal Dhall single-line comments start with `--` and ends at a newline. For
+example:
+
+```dhall
+-- single-line comment
+0
+```
+
+A `dhall-docs` valid single-line comment starts with `--|` and a single whitespace
+character. For example:
+
+```dhall
+--|␣foo
+```
+
+You can span your documentation in several single-line comments by writing `--` and two
+(2) whitespaces:
+
+```dhall
+--|␣foo
+--␣␣bar
+--␣␣␣␣␣␣baz
+```
+
+The `--` prefix defines the base indentation for any line. That is, on the above
+example `dhall-docs` will extract the following contents:
+
+```
+foo
+bar
+␣␣␣␣baz
+```
+
+If you would like to force an empty line on the documentation output, place an
+empty single line comment. On this example:
+
+```dhall
+--| foo
+--
+-- bar
+```
+
+`dhall-docs` will extract:
+
+```dhall
+foo
+
+bar
+```
+
+The empty `--` line should not have the two (2) whitespaces.
+
+If between two single-line comments there is one (1) or more empty lines, the
+latter comments will be ignored. On this example:
+
+
+```dhall
+--| foo
+-- bar
+
+-- baz
+```
+
+`dhall-docs` will only capture this text:
+
+```
+foo
+bar
+```
+
+In a set of subsequent single-line comments, all lines before the one that has
+the `|` character will be ignored, meaning that if any line on the set doesn't
+have the `|` marker, no text will be extracted for the generated documentation.
+
+On this example:
+
+```dhall
+-- foo
+-- bar
+--| baz
+-- qux
+```
+
+the following text will be extracted:
+
+```dhall
+baz
+qux
+```
+
+and this set of single-line comments:
+
+```dhall
+-- foo
+-- bar
+-- baz
+```
+
+will be ignored by the tool.
+
+The set of `--` lines needs to be aligned with the same number of preceding
+characters, meaning that a set of lines like this:
+
+```dhall
+--| foo
+ -- bar
+ -- baz
+```
+
+is invalid: `dhall-docs` will ignore this on the generated documentation and
+a warning will be logged on the console.
+
+To end, if there are language tokens in-between a set of lines, the lines after
+those tokens will be ignored. On this example:
+
+```dhall
+--| foo
+,
+-- bar
+```
+
+the extracted text will be the following:
+
+ foo
+
+Here is an example of using this type of comments in a Dhall file:
+
+```dhall
+--| # My header
+--
+-- * 1
+-- * 2
+
+let --| foo
+ -- bar
+ a = True
+
+in { a }
+
+```
+
+### Mixing the two type of comments
+
+In a single Dhall file, you can use any type of comments to document your code,
+but there is a restriction.
+
+Two subsequent `dhall-docs` comments (whether single-line or
+block comments) are forbidden: `dhall-docs` will reject them _and_ log a warning
+on the console, but you can freely place any non-dhall comment after a `dhall-docs`
+comment. All of the following examples are invalid:
+
+```dhall
+{-|
+ foo -}
+{-|
+ bar -}
+```
+
+```dhall
+{-|
+ foo -}
+--| bar
+```
+
+```dhall
+{-|
+ foo -}
+{- -}
+{-|
+ qux -}
+```
+
+```dhall
+--| foo
+-- bar
+{-|
+ qux -}
+```
+
+```dhall
+--| foo
+-- bar
+{- -}
+--| qux
+-- baz
+```
+
+Note that non `dhall-docs` comments are ignored in the above examples.
+
+
+### Validating the extracted text
+
+After extracting the text on a valid `dhall-docs` comment, it will be passed
+to [`mmark`]. If there is a [CommonMark] parse error, an error will be logged
+on the console _but_ the extracted text will be rendered in the documentation exactly as it was extracted.
+
+### Supported annotated elements
+
+A limitation of the `dhall` parser is that it doesn't preserve _all_ the whitespaces
+of a Dhall source file, but preserves the enough to write useful documentation.
+`dhall-docs` supports the following comments:
+
+* The header of a file:
+
+ ```dhall
+ {-| this is the header
+ -}
+ let a = 1
+ in a
+ ```
+
+## Development
+
+### `ghci`
+
+If you want to open the `ghci` repl on this package using `stack`, you have to
+provide an additional flag:
+
+```bash
+stack ghci dhall-docs --flag dhall-docs:ghci-data-files
+```
+
+... otherwise the CSS and JS files won't be properly embedded
+
+
+### Running tests
+
+We have a golden-test setup to test the whole tool. If you add a new test file
+or introduced a change that changed the way the documentation is generated, do
+the following:
+
+1. On `tasty/Main.hs` search for the usages of `Silver.defaultMain` and replace
+ them with `Test.Tasty.defaultMain`
+2. Execute the test runner with the `--accept` flag. In stack you could do:
+ `stack test dhall-docs:tasty --test-arguments --accept`
+3. After updating the golden files, revert the change on (1)
+
+### Generated docs on Hydra
+
+Our hydra job sets builds documentation for the following test packages:
+
+* The [Dhall Prelude](https://prelude.dhall-lang.org)
+* The [dhall-docs test demo package](./tasty/data/package)
+
+If you're in a PR, you can see the generated documentation by navigating to:
+
+https://hydra.dhall-lang.org/job/dhall-haskell/${PR_NUMBER}/${PACKAGE_NAME}/latest/download/1/docs
+
+... where `${PACKAGE_NAME}` is one of the following:
+
+* `prelude-dhall-docs` if you want to see Dhall's Prelude documentation
+* `kubernetes-dhall-docs` if you want to see the `dhall-kubernetes` documentation package
+* `test-dhall-docs` if you want to see the test demo package
+
+If you want to see the latest generated docs on the `master` branch, visit:
+
+https://hydra.dhall-lang.org/job/dhall-haskell/master/${PACKAGE_NAME}/latest/download/1/docs
+
+[CommonMark]: https://commonmark.org/
+[indented-code-blocks]: https://spec.commonmark.org/0.12/#indented-code-blocks
+[`mmark`]: https://hackage.haskell.org/package/mmark
+[Dhall multi-line strings]: https://github.com/dhall-lang/dhall-lang/blob/master/standard/multiline.md#indentation
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.4
+Version: 1.0.5
Cabal-Version: >=1.10
Build-Type: Simple
Tested-With: GHC == 8.6.1
@@ -22,6 +22,7 @@
Category: Compiler
Extra-Source-Files:
CHANGELOG.md
+ README.md
tasty/data/package/*.dhall
tasty/data/package/a/*.dhall
tasty/data/package/a/b/*.dhall
@@ -37,6 +38,7 @@
tasty/data/golden/a/b/*.html
tasty/data/golden/a/b/c/*.html
tasty/data/golden/deep/nested/folder/*.html
+ tasty/data/golden/deep/nested/*.html
tasty/data/comments/empty/*.txt
tasty/data/comments/invalid/*.txt
tasty/data/comments/valid/*.txt
@@ -61,11 +63,11 @@
Hs-Source-Dirs: src
Build-Depends:
base >= 4.11.0.0 && < 5 ,
- bytestring < 0.11,
+ bytestring < 0.12,
containers ,
cryptonite < 0.29,
directory >= 1.3.0.0 && < 1.4 ,
- dhall >= 1.35.0 && < 1.39,
+ dhall >= 1.38.0 && < 1.39,
file-embed >= 0.0.10.0 ,
filepath >= 1.4 && < 1.5 ,
lens-family-core >= 1.0.0 && < 2.2 ,
@@ -120,7 +122,7 @@
base ,
directory,
filepath < 1.5 ,
- doctest >= 0.7.0 && < 0.18
+ doctest >= 0.7.0 && < 0.19
Other-Extensions: OverloadedStrings RecordWildCards
Default-Language: Haskell2010
@@ -135,7 +137,6 @@
dhall ,
dhall-docs ,
foldl < 1.5 ,
- HaXml >= 1.25.5 ,
path ,
path-io ,
pretty >= 1.1.1.1 ,
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
@@ -61,6 +61,7 @@
import qualified Data.List
import qualified Data.List.NonEmpty as NonEmpty
import qualified Data.Map.Strict as Map
+import qualified Data.Map.Merge.Strict as Map.Merge
import qualified Data.Maybe
import qualified Data.Maybe as Maybe
import qualified Data.Text
@@ -80,6 +81,7 @@
-- | The result of the doc-generator pure component
data GeneratedDocs a = GeneratedDocs [DocsGenWarning] a
+ deriving (Show)
instance Functor GeneratedDocs where
fmap f (GeneratedDocs w a) = GeneratedDocs w (f a)
@@ -140,7 +142,7 @@
-- | Extracted text from from Dhall file's comments
newtype FileComments = FileComments
{ headerComment :: Maybe DhallDocsText -- ^ 'Nothing' if no comment or if invalid
- }
+ } deriving (Show)
-- | Represents a Dhall file that can be rendered as documentation.
-- If you'd like to improve or add features to a .dhall documentation page,
@@ -154,7 +156,7 @@
, examples :: [Expr Void Import] -- ^ Examples extracted from assertions
-- in the file
, fileComments :: FileComments
- }
+ } deriving (Show)
{-| Takes a list of files paths with their contents and returns the list of
valid `DhallFile`s.
@@ -332,11 +334,11 @@
`a/b/`, but yes on `a/b/c/` in the last one there is the @b.dhall@ file
-}
createIndexes :: Text -> CharacterSet -> [DhallFile] -> [(Path Rel File, Text)]
-createIndexes packageName characterSet files = map toIndex dirToDirsAndFilesMapAssocs
+createIndexes packageName characterSet dhallFiles = 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) files
+ dirToFilesMap = Map.unionsWith (<>) $ map toMap $ Data.List.sortBy (compare `on` path) dhallFiles
where
toMap :: DhallFile -> Map (Path Rel Dir) [DhallFile]
toMap dhallFile = Map.singleton (Path.parent $ path dhallFile) [dhallFile]
@@ -346,43 +348,34 @@
documentation to get more information.
-}
dirToDirsMap :: Map (Path Rel Dir) [Path Rel Dir]
- dirToDirsMap = Map.map removeHereDir $ foldr go initialMap dirs
+ dirToDirsMap = foldr cons Map.empty dirs
where
- -- > removeHeredir [$(mkRelDir "a"), $(mkRelDir ".")]
- -- [$(mkRelDir "a")]
- removeHereDir :: [Path Rel Dir] -> [Path Rel Dir]
- removeHereDir = filter f
+ dirs = filter keep (Map.keys dirToFilesMap)
where
- f :: Path Rel Dir -> Bool
- f reldir = Path.parent reldir /= reldir
-
- dirs :: [Path Rel Dir]
- dirs = Map.keys dirToFilesMap
-
- initialMap :: Map (Path Rel Dir) [Path Rel Dir]
- initialMap = Map.fromList $ map (,[]) dirs
+ keep reldir = Path.parent reldir /= reldir
- go :: Path Rel Dir -> Map (Path Rel Dir) [Path Rel Dir] -> Map (Path Rel Dir) [Path Rel Dir]
- go d dirMap = Map.adjust ([d] <>) (key $ Path.parent d) dirMap
- where
- key :: Path Rel Dir -> Path Rel Dir
- key dir = if dir `Map.member` dirMap then dir else key $ Path.parent dir
+ cons d = Map.insertWith (<>) (Path.parent d) [d]
dirToDirsAndFilesMapAssocs :: [(Path Rel Dir, ([DhallFile], [Path Rel Dir]))]
- dirToDirsAndFilesMapAssocs = Map.assocs $ Map.mapWithKey f dirToFilesMap
+ dirToDirsAndFilesMapAssocs = Map.assocs $
+ Map.Merge.merge
+ (Map.Merge.mapMissing onlyFiles)
+ (Map.Merge.mapMissing onlyDirectories)
+ (Map.Merge.zipWithMatched both)
+ dirToFilesMap
+ dirToDirsMap
where
- f :: Path Rel Dir -> [DhallFile] -> ([DhallFile], [Path Rel Dir])
- f dir dhallFiles = case dirToDirsMap Map.!? dir of
- Nothing -> fileAnIssue "dirToDirsAndFilesMapAssocs"
- Just dirs -> (dhallFiles, dirs)
+ onlyFiles _ files = (files, [] )
+ onlyDirectories _ directories = ([] , directories)
+ both _ files directories = (files, directories)
toIndex :: (Path Rel Dir, ([DhallFile], [Path Rel Dir])) -> (Path Rel File, Text)
- toIndex (indexDir, (dhallFiles, dirs)) =
+ toIndex (indexDir, (files, dirs)) =
(indexDir $(Path.mkRelFile "index.html"), Text.Lazy.toStrict $ Lucid.renderText html)
where
html = indexToHtml
indexDir
- (map (\DhallFile{..} -> (stripPrefix $ addHtmlExt path, mType)) dhallFiles)
+ (map (\DhallFile{..} -> (stripPrefix $ addHtmlExt path, mType)) files)
(map stripPrefix dirs)
DocParams { relativeResourcesPath = resolveRelativePath indexDir, packageName, characterSet }
diff --git a/tasty/Main.hs b/tasty/Main.hs
--- a/tasty/Main.hs
+++ b/tasty/Main.hs
@@ -28,8 +28,6 @@
import qualified Test.Tasty.Silver as Silver
import qualified Test.Tasty.Silver.Interactive as Silver
import qualified Text.PrettyPrint as Pretty
-import qualified Text.XML.HaXml.Html.Parse as HaXml
-import qualified Text.XML.HaXml.Pretty as HaXml
import qualified Turtle
main :: IO ()
@@ -70,12 +68,11 @@
where
goldenFilePath = Path.fromRelFile $ goldenDir testFile
testName = Path.fromRelFile testFile
- action = return prettyHtmlDoc
+ action = (return . Data.Text.unpack . prettyHtml) text
converter = Data.Text.pack
- prettyHtmlDoc = Pretty.render
- $ HaXml.document
- $ HaXml.htmlParse testName (Data.Text.unpack text)
+ -- Simply add some line breaks so the result is easier to read.
+ prettyHtml = Data.Text.replace "><" ">\n<"
getCommentTests :: IO TestTree
getCommentTests = do
diff --git a/tasty/data/golden/ImportAsType.dhall.html b/tasty/data/golden/ImportAsType.dhall.html
--- a/tasty/data/golden/ImportAsType.dhall.html
+++ b/tasty/data/golden/ImportAsType.dhall.html
@@ -1,50 +1,44 @@
-/ImportAsType.dhall
{-| This example should throw a warning since after the `|` marker of the opening brace there *must* be a newline (either \n or \r\n) -} {-| bar -} {=}
{-| This example should throw a warning since after the `|` marker of the opening brace there *must* be a newline (either \n or \r\n) -} {-| bar -} {=}
+
let DeliveryStatus = < Sent: Pair Natural Text {-| Message has been _sent_. It carries a ./Pair.dhall reference containing on the `first` field number of retries and on the `second` field the delivered text -} | InProgress -- | Message is on the way! | InQueue -- | Delivery for this message **hasn't** started >
--| This file contains a markdown error right here ` -- did you notice it?
+ let Pair = ./Pair.dhall
+
+ let DeliveryStatus = < Sent: Pair Natural Text {-| Message has been _sent_. It carries a ./Pair.dhall reference containing on the `first` field number of retries and on the `second` field the delivered text -} | InProgress -- | Message is on the way! | InQueue -- | Delivery for this message **hasn't** started >
+ in DeliveryStatus
+
+
{-| `dhall-docs` will detect some names (record fields, let-bindings and lam-bindings) are unused and therefore won't be highlighted -}
+ let unused = 1 let used = 3
+ let unusedRecord = { foo = 1 } let usedRecord = { foo = 1 }
+ let f = \(unused : Bool) -> \(used : Natural) -> \(r : { unused : Text, used : Natural}) -> used + r.used
+
+ in used + usedRecord.foo + f True 1 { unused = "foo", used = 3 }
+
A complex example of jump-to-definition on let-bindings
-
Source
{-| A complex example of jump-to-definition on let-bindings -} let fun = λ(a : Text) -> λ(b : Text) -> λ(c : Text) -> λ(d : Text) -> [ a ++ b, b ++ c, c ++ d, d ++ a ]
A complex example of jump-to-definition on let-bindings
+
+
Source
+
+
{-| A complex example of jump-to-definition on let-bindings -} let fun = λ(a : Text) -> λ(b : Text) -> λ(c : Text) -> λ(d : Text) -> [ a ++ b, b ++ c, c ++ d, d ++ a ]
+ in fun
+
+
This examples shows a demo of jumping to a let-binding definition. If you hover
-the a paramter, the front-end will highlight all of its usages and if you
-click it you will navigate to its definition.
-
The amount of empty lines left are intentional to show you how the browser jumps
+
+
This examples shows a demo of jumping to a let-binding definition. If you hover
+the a paramter, the front-end will highlight all of its usages and if you
+click it you will navigate to its definition.
+
The amount of empty lines left are intentional to show you how the browser jumps
to the declaration of a
-
Source
{-| This examples shows a demo of jumping to a let-binding definition. If you hover the `a` paramter, the front-end will highlight all of its usages and if you click it you will navigate to its definition.
The amount of empty lines left are intentional to show you how the browser jumps to the declaration of a -} let fun = \(v : Text) ->
{-| This examples shows a demo of jumping to a let-binding definition. If you hover the `a` paramter, the front-end will highlight all of its usages and if you click it you will navigate to its definition.
+ The amount of empty lines left are intentional to show you how the browser jumps to the declaration of a -} let fun = \(v : Text) ->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ v
+
+
+
+ in fun
+
+
On this example, we introduce the a variable in the two parameters of the
-fun function and the jump-to-definition engine correctly highlights the usage
+
+
On this example, we introduce the a variable in the two parameters of the
+fun function and the jump-to-definition engine correctly highlights the usage
when indexes are used
-
Examples
fun "a" "b" ≡ [ "ab" ]
Source
{-| On this example, we introduce the `a` variable in the two parameters of the `fun` function and the jump-to-definition engine correctly highlights the usage when indexes are used -} let fun = λ(a : Text) -> λ(a : Text) -> [ a@1 ++ a@0 ]
{-| On this example, we introduce the `a` variable in the two parameters of the `fun` function and the jump-to-definition engine correctly highlights the usage when indexes are used -} let fun = λ(a : Text) -> λ(a : Text) -> [ a@1 ++ a@0 ]
+ let example0 = assert : fun "a" "b" === ["ab"]
+ in fun
+
+
+
This tests shows that the feature works for quoted vars on function parameters
as well
-
Examples
fun "a" "b" ≡ [ "ab" ]
Source
{-| This tests shows that the feature works for quoted vars on function parameters as well -} let fun = λ(`param 1` : Text) -> λ(`param 2` : Text) -> [ `param 1` ++ `param 2` ]
{-| This tests shows that the feature works for quoted vars on function parameters as well -} let fun = λ(`param 1` : Text) -> λ(`param 2` : Text) -> [ `param 1` ++ `param 2` ]
+ let example0 = assert : fun "a" "b" === ["ab"]
+ in fun
+
+
+
On this example, the first parameter a is shadowed with the second declaration.
-The jump-to-definintion on the usage of a should not highlight the first declaration,
+
+
On this example, the first parameter a is shadowed with the second declaration.
+The jump-to-definintion on the usage of a should not highlight the first declaration,
and interacting with the first declaration should not change the others
-
Examples
fun "a" "b" ≡ [ "bb" ]
Source
{-| On this example, the first parameter `a` is shadowed with the second declaration. The jump-to-definintion on the usage of `a` should not highlight the first declaration, and interacting with the first declaration should not change the others -} let fun = λ(a : Text) -> λ(a : Text) -> [ a ++ a ]
{-| On this example, the first parameter `a` is shadowed with the second declaration. The jump-to-definintion on the usage of `a` should not highlight the first declaration, and interacting with the first declaration should not change the others -} let fun = λ(a : Text) -> λ(a : Text) -> [ a ++ a ]
+ let example0 = assert : fun "a" "b" === ["bb"]
+ in fun
+
+
+
This examples shows a demo of jumping to a let-binding definition. If you hover
-the a variable, the front-end will highlight all of its usages and if you
-click it you will navigate to its definition.
-
The amount of empty lines left are intentional to show you how the browser jumps
+
+
This examples shows a demo of jumping to a let-binding definition. If you hover
+the a variable, the front-end will highlight all of its usages and if you
+click it you will navigate to its definition.
+
The amount of empty lines left are intentional to show you how the browser jumps
to the declaration of a
-
Source
{-| This examples shows a demo of jumping to a let-binding definition. If you hover the `a` variable, the front-end will highlight all of its usages and if you click it you will navigate to its definition.
The amount of empty lines left are intentional to show you how the browser jumps to the declaration of a -} let a = 1
{-| This examples shows a demo of jumping to a let-binding definition. If you hover the `a` variable, the front-end will highlight all of its usages and if you click it you will navigate to its definition.
+ The amount of empty lines left are intentional to show you how the browser jumps to the declaration of a -} let a = 1
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ in
+
+a
+
+
Although we have a similar example on this file,
this example showcases the jump-to-definition feature when indexes are used.
-
Source
{-| Although we have a similar example on this [file](./RenderTypeIndexesExample.dhall), this example showcases the jump-to-definition feature when indexes are used. -} let a = 1
{-| Although we have a similar example on this [file](./RenderTypeIndexesExample.dhall), this example showcases the jump-to-definition feature when indexes are used. -} let a = 1
+ let a = 2
+ in a@1
+
+
This test cases shows that the feature works with quoted variables
+
+
Source
+
+
{-| This test cases shows that the feature works with quoted variables -} let `quoted variable` = 1
+ let nonQuoted = 2
+ in `quoted variable` + `nonQuoted`
+
+
On this example, the first declaration of variable a is shadowed with the
+later declaration. The jump-to-definintion on the usage of a
should not highlight the first declaration, and interacting with the first
declaration should not change the others
-
Source
{-| On this example, the first declaration of variable `a` is shadowed with the later declaration. The jump-to-definintion on the usage of `a` should not highlight the first declaration, and interacting with the first declaration should not change the others -} let a = 1
{-| On this example, the first declaration of variable `a` is shadowed with the later declaration. The jump-to-definintion on the usage of `a` should not highlight the first declaration, and interacting with the first declaration should not change the others -} let a = 1
+ let a = 2
+ in a
+
+
A complex example of jump-to-definition on let-bindings
+
+
Source
+
+
{-| A complex example of jump-to-definition on let-bindings -} let f = \(f : Natural) -> let a = 1 in f + a
+
+ let a = f 1
+ let b = a + f 3
+ in b
+
+
On this example, dhall-docs will detect that the variable a and b is of
record-type. If on a selector-expression the field is not found on the type,
no-link will be created
-
Source
{-| On this example, `dhall-docs` will detect that the variable `a` and `b` is of record-type. If on a selector-expression the field is not found on the type, no-link will be created
{-| On this example, `dhall-docs` will detect that the variable `a` and `b` is of record-type. If on a selector-expression the field is not found on the type, no-link will be created
+ -} let a = { x = "foo" } let b = False
+ in a.y + b.`does not exist`
+
On this example, dhall-docs will detect that the variable a is annotated
-with a type, but it will ignore it anyways. On let-bindings, dhall-docs infers
+
+
On this example, dhall-docs will detect that the variable a is annotated
+with a type, but it will ignore it anyways. On let-bindings, dhall-docs infers
the type of the variable from the bounded expression. As a consequence, on
-this example, hovering the x on the selector-expression will highlight the
-x label on the record-literal
-
Source
{-| On this example, `dhall-docs` will detect that the variable `a` is annotated with a type, but it will ignore it anyways. On let-bindings, `dhall-docs` infers the type of the variable from the bounded expression. As a consequence, on this example, hovering the `x` on the selector-expression will highlight the `x` label on the record-literal -} let a : Bool = { x = "foo" }
+this example, hovering the x on the selector-expression will highlight the
+x label on the record-literal
+
+
Source
+
+
{-| On this example, `dhall-docs` will detect that the variable `a` is annotated with a type, but it will ignore it anyways. On let-bindings, `dhall-docs` infers the type of the variable from the bounded expression. As a consequence, on this example, hovering the `x` on the selector-expression will highlight the `x` label on the record-literal -} let a : Bool = { x = "foo" }
+ in a.x
+
+
On this example, even when the variable a is annotated with a record-type,
+dhall-docs will infer the actual type from the bounded value.
+
All interactions with fields on selector-expressions won't affect the rendered-type.
+
(The example is intended to not type-check as a Dhall expression)
+
+
Source
+
+
{-| On this example, even when the variable `a` is annotated with a record-type, `dhall-docs` will infer the actual type from the bounded value.
+ All interactions with fields on selector-expressions won't affect the rendered-type.
+ (The example is intended to not type-check as a Dhall expression) -} let a : { x : Text } = { x = "foo", y = "bar" }
+ in a.x ++ a.y
+
+
On this example, dhall-docs will detect that the variable a is bounded
-to a record-literal. When the user clicks on the field in the a.field, it
-will jump to the definition of that field in the source code i.e. to the field
+
+
On this example, dhall-docs will detect that the variable a is bounded
+to a record-literal. When the user clicks on the field in the a.field, it
+will jump to the definition of that field in the source code i.e. to the field
key in the record literal
-
Source
{-| On this example, `dhall-docs` will detect that the variable `a` is bounded to a record-literal. When the user clicks on the `field` in the `a.field`, it will jump to the definition of that field in the source code i.e. to the `field` key in the record literal -} let a = { field = "foo" }
{-| On this example, `dhall-docs` will detect that the variable `a` is bounded to a record-literal. When the user clicks on the `field` in the `a.field`, it will jump to the definition of that field in the source code i.e. to the `field` key in the record literal -} let a = { field = "foo" }
+ in Text/show a.field
+
+
A complex example of the jump-to-definition feature on record literals.
+
+
Source
+
+
{-| A complex example of the jump-to-definition feature on record literals. -} let a = { foo = "bar", number = +1 }
+ let b = { foo = "bar", number = +1 }
+ in a.foo ++ Integer/show a.number ++ b.foo ++ Integer/show b.number
+
+
On this example, dhall-docs will detect that the variable a is bounded
-to a record literal. It will also detect that the field key from the record
-literal is another record literal. When the user clicks deep from the
-a.field.deep, it will jump to the definition of that variable in the source
+
+
On this example, dhall-docs will detect that the variable a is bounded
+to a record literal. It will also detect that the field key from the record
+literal is another record literal. When the user clicks deep from the
+a.field.deep, it will jump to the definition of that variable in the source
code.
-
Source
{-| On this example, `dhall-docs` will detect that the variable `a` is bounded to a record literal. It will also detect that the `field` key from the record literal is another record literal. When the user clicks `deep` from the `a.field.deep`, it will jump to the definition of that variable in the source code. -} let a = { field = { deep = "bar" } }
{-| On this example, `dhall-docs` will detect that the variable `a` is bounded to a record literal. It will also detect that the `field` key from the record literal is another record literal. When the user clicks `deep` from the `a.field.deep`, it will jump to the definition of that variable in the source code. -} let a = { field = { deep = "bar" } }
+ in Text/show a.field.deep
+
+
On this example, dhall-docs will detect that the argument a of the only
function in this file is of record type. Therefore, any interactions on selector
-expressions over the a variable will interact with the fields on the record-type.
-
Note that the treatment for Lam variables is different from Let bindings:
+expressions over the a variable will interact with the fields on the record-type.
+
Note that the treatment for Lam variables is different from Let bindings:
the annotation doesn't affect on the later case. This can be seen in the
-test case for let bindings
-
Source
{-| On this example, `dhall-docs` will detect that the argument `a` of the only function in this file is of record type. Therefore, any interactions on selector expressions over the `a` variable will interact with the fields on the record-type.
Note that the treatment for `Lam` variables is different from `Let` bindings: the annotation doesn't affect on the later case. This can be seen in the [test case for let bindings](./JumpToRecordFieldWhenLetAnnotationPresentShouldIgnoreAnnotation.dhall) -}
λ(b : Type) → λ(c : Type) → λ(a : { list : List b, cons : b → c → c, nil : c }) → List/fold ba.listca.consa.nil
{-| On this example, `dhall-docs` will detect that the argument `a` of the only function in this file is of record type. Therefore, any interactions on selector expressions over the `a` variable will interact with the fields on the record-type.
+ Note that the treatment for `Lam` variables is different from `Let` bindings: the annotation doesn't affect on the later case. This can be seen in the [test case for let bindings](./JumpToRecordFieldWhenLetAnnotationPresentShouldIgnoreAnnotation.dhall) -}
+ λ(b : Type) → λ(c : Type) → λ(a : { list : List b, cons : b → c → c, nil : c }) → List/fold ba.listca.consa.nil
+
+
On this example, dhall-docs will detect that the variable a is bounded
-to a record literal. It will also be aware that that the attribute x. When
-the user clicks the x from a.x, it will jump to the x punned-entry
-
Source
{-| On this example, `dhall-docs` will detect that the variable `a` is bounded to a record literal. It will also be aware that that the attribute `x`. When the user clicks the `x` from `a.x`, it will jump to the `x` punned-entry -} let x = 1 let a = { x }
On this example, dhall-docs will detect that the variable a is bounded
+to a record literal. It will also be aware that that the attribute x. When
+the user clicks the x from a.x, it will jump to the x punned-entry
+
+
Source
+
+
{-| On this example, `dhall-docs` will detect that the variable `a` is bounded to a record literal. It will also be aware that that the attribute `x`. When the user clicks the `x` from `a.x`, it will jump to the `x` punned-entry -} let x = 1 let a = { x }
+ in a.x
+
+
On this example, dhall-docs will detect that the variable b is bounded
-to the value of a, and the later is bounded to a record-literal. All selector
-expressions over b will interact with the record-literal assigned to a, since
+
+
On this example, dhall-docs will detect that the variable b is bounded
+to the value of a, and the later is bounded to a record-literal. All selector
+expressions over b will interact with the record-literal assigned to a, since
that is the actual definition of the fields.
-
Source
{-| On this example, `dhall-docs` will detect that the variable `b` is bounded to the value of `a`, and the later is bounded to a record-literal. All selector expressions over `b` will interact with the record-literal assigned to `a`, since that is the actual definition of the fields. -} let a = { x = 1 } let b = a
{-| On this example, `dhall-docs` will detect that the variable `b` is bounded to the value of `a`, and the later is bounded to a record-literal. All selector expressions over `b` will interact with the record-literal assigned to `a`, since that is the actual definition of the fields. -} let a = { x = 1 } let b = a
+
+ in a.x + b.x
+
+
{-| On this example, `dhall-docs` will detect that the variable `a` is bounded to a record literal and it will be aware that it uses dot-syntax.
+ When the user clicks `x` from `a.x`, it will jump to the `x` on the record-literal. The same applies for each other field. -} let a = { x.y.z = 1 }
+ let ax = a.x
+ let axy = a.x.y
+ let axyz = a.x.y.z
+
+ in ax.y.z + axy.z + axyz
+
+
{-| Example taken from [dhall documentation](https://docs.dhall-lang.org/tutorials/Language-Tour.html#prelude) -}
+
+ let List/generate = https://prelude.dhall-lang.org/v15.0.0/List/generate
+
+ in List/generate 10 Text (\(n : Natural) -> "Result #${Natural/show n}")
+
+
```haskell main = putStrLn "dhall rulez" ``` -} { remitent: Text --| Remitent name , deliveryStatus: ./DeliveryStatus.dhall --| Status , body: Text --| Message body }
+
+
As somebody said,
+
+
The best way to code is to not code
+
+
Here I show you some haskell code
+
+main = putStrLn "dhall rulez"
+
+
+
+
Source
+
+
{-| # Heading 1
+ ## Heading 2
+ ### Heading 3
+ #### Heading 4
+ ##### Heading 5
+ ###### Heading 6
+ Message data type for our _messaging-system_ config.
+ It is similar to the `kafka` message dto. testing again another random text.
+ **NOTE**: This is really important to know
+ This allows you to:
+ * Send messages * Receive messages, knowing that: - nothing works (?) - weird huh
+ As somebody said,
+ > The best way to code is to not code
+ Here I show you some haskell code
+ ```haskell main = putStrLn "dhall rulez" ``` -} { remitent: Text --| Remitent name , deliveryStatus: ./DeliveryStatus.dhall --| Status , body: Text --| Message body }
+
let Pair : forall(A: Type) -- | Type of first position -> forall(B: Type) -- | Type of second position -> Type = λ(A: Type) -> λ(B: Type) -> {first: A, second: B}
+ {-| Just a *Pair* right here -}
+ let Pair
+ : forall(A: Type) -- | Type of first position -> forall(B: Type) -- | Type of second position -> Type = λ(A: Type) -> λ(B: Type) -> {first: A, second: B}
+ in Pair
+
+
{-| This example shows that `dhall-docs` will find render the correct type on the index respecting variable indices -}
+ let x : Bool = True let x : Natural = 1
+ in x@1
+
+
This expression contains type annotations on both the let binding and on the
-body of the let expression. The documentation generator prefers to use the
+
+
This expression contains type annotations on both the let binding and on the
+body of the let expression. The documentation generator prefers to use the
latter annotation.
-
Source
{-| This expression contains type annotations on both the `let` binding and on the body of the `let` expression. The documentation generator prefers to use the latter annotation. -} let x = 1
{-| This expression contains type annotations on both the `let` binding and on the body of the `let` expression. The documentation generator prefers to use the latter annotation. -} let x = 1
+ let y = Natural
+ in x : y
+
+
{- Check if a natural is even or not returning an union data-type -} let my-even : Natural → < even | odd > = λ(n : Natural) → if Natural/even n then < even | odd>.even else < even | odd >.odd
{- Check if a natural is even or not returning an union data-type -} let my-even
+ : Natural → < even | odd > = λ(n : Natural) → if Natural/even n then < even | odd>.even else < even | odd >.odd
+ let example0 = assert : my-even 1 === <even | odd>.odd let example0 = assert : my-even 2 === <even | odd>.even
+ in my-even
+
+
