Announcing the first experimental release of dhall-docs

#1

Hi there!

I’m happy to announce that dhall-docs has been released!

The tool is still on the development phase, there are things that probably will change but it’s somewhat useful to actually start generating some documentation.

The features of the tool are:

  • Header documentation extracting;
  • Examples from assertions;
  • Rendered source code;
  • Navigatable breadcrumbs;
  • Dark & Light mode

On the project README you can check how to use it: https://github.com/dhall-lang/dhall-haskell/tree/master/dhall-docs

Here you can see a demo of the generated documentation for the Dhall Prelude: https://hydra.dhall-lang.org/build/64022/download/1/docs/

The package has been released on hackage: https://hackage.haskell.org/package/dhall-docs

I’ve been blogging about the development process. This is the first post: https://dev.to/german1608/gsoc-2020-dhall-documentation-generator-37l. There you can see the index for the other ones :slight_smile:

Please comment in this thread with any suggestions or improvements that you think might help dhall-docs get better.

9 Likes
#2

time to document my projects :sunglasses:

3 Likes
#3

Awesome! (But you’ve made a lot of commenting work for me. :wink: )

FYI the source repo on hackage seems to point to dhall-json

Screenshot_2020-07-10%20dhall-docs%20Generate%20HTML%20docs%20from%20a%20dhall%20package

1 Like
#4

Oops! Well noticed @SiriusStarr

#5

Well done @german1608 ! It’s already looking great :slight_smile: I had a minor issue though when trying to run the tool on a project with a .git folder, and I think https://github.com/dhall-lang/dhall-haskell/pull/1910 should fix the failure.

#6

I may be dumb, but is there a reference anywhere yet for the expected format of comments and such? (e.g. something like this for haddock or this for elm)

#7

@SiriusStarr we’ve been discussing that weeks ago. Currently, we only parse the comment headers and it doesn’t need a specific format for the comments. The comment markup syntax is CommonMark: a strict flavour of Markdown.

The discussion about your regard is on this issue: https://github.com/dhall-lang/dhall-haskell/issues/1868

#8

Awesome, thanks. I’d probably add something along those lines

Currently, we only parse the comment headers and it doesn’t need a specific format for the comments. The comment markup syntax is CommonMark: a strict flavour of Markdown.

to the readme or something (unless it already says that somewhere and I just missed it, which is very possible), just so more people like me don’t waste your time asking. :wink:

#9

You didn’t missed anything, I forgot to document that on the README :sweat_smile:

This PR https://github.com/dhall-lang/dhall-haskell/pull/1912 improves documentation for future users

3 Likes