Current commonly used tool for previewing docs?

Learn
1

Hi,

What does this community tend to use these days for previewing docs of a module you’re working on?

I see some posts about ‘elm-doc-preview’ from years ago. Is there a community consensus around good tools these days?

Thanks!

2

Yes, elm-doc-preview is fantastic, it works very nicely. Highly recommended, and that is indeed what the community uses. The web app is quite handy for sharing work-in-progress docs as well: https://elm-doc-preview.netlify.app/.

I have a doc with some tools and conventions for Elm packages as well: GitHub - dillonkearns/idiomatic-elm-package-guide: Everything you need to know to publish a useful, idiomatic Elm package!.

1 Like
3

Wonderful, thanks! I’ll look into the idiomatic-elm-package-guide too.

1 Like
4

@dillonkearns - I really like the idiomatic elm package guide, and thanks for writing it.

You suggest “On the macro level, try starting with an examples folder (i.e. examples-Driven Development). Start with a simple yet meaningful example.” I really like that idea. Do those examples get turned into runnable tests? Or do they stay with the repo in Github in an ‘examples’ folder, and just don’t get exposed as modules? Thanks!

1 Like
5

Good question! In the case of my elm-graphql package, which does a lot of code generation with the accompanying NPM tool, I check in the generated code in the examples folder and I do automated testing on that. It’s been a great workflow! We talked about that a bit in this Elm Radio segment in a codegen episode. In some cases it works really nicely to run automated tests against the examples in your examples/ folder, and in other cases it might not be that valuable, but it’s definitely worth considering!

We also talked about some other API design techniques in this episode:

2 Likes
6

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.