Elm-doc-preview 3: Applications support & offline packages documentation server

elm-doc-preview 3.0.0 is a complete rewrite with two new major features:

  • Applications are now completely supported, see README to understand how this works.
  • The web application is now an offline clone of package.elm-lang.org, but using your local cached packages. You can search packages, browse sources, see how your previewed package will appear in the list, etc. And it can be run even without any package or application to preview.

It is released as a release candidate (3.0.0-rc1 for now) until I get enough feedback, so please test it on any package or application if you can:

npm install -g elm-doc-preview@next

Edit: 3.0.0 has been released:

npm install -g elm-doc-preview

The new version also resolves all know bugs and features requests.

Example of elm-spa-example with some documentation exposed:

Browse the documentation online


Example of cached packages search page:


Example of a cached package documention (it includes the information of elm-package-info that can displayed offline):

26 Likes

Note that currently, it needs a globally available elm command to be able to build generated packages in a system temporary directory.

If this is an issue for you, tell me, it could eventually build in elm-stuff subdirectory instead.

1 Like

Cool updates!

I always install Elm locally with npm install to explicitly choose the version of elm command such as this package.json.
So, it is super helpful for me to make it work without globally available elm command.

3 Likes

elm-doc-preview@3.0.0-rc2 has been released as elm-doc-preview@next.

elm global command is not required anymore.

It also includes minor logs, documentation and cosmetic improvements.

2 Likes

Love the idea of being able to view documentation for an application. Could be especially useful for team projects to use as a way of documenting things collectively for the team.

When I try to run it I get:

/home/rupert/.npm-global/lib/node_modules/elm-doc-preview/node_modules/package-json/index.js:36
                ...options
                ^^^
SyntaxError: Unexpected token ...

Perhaps my NodeJS is too old? This computer currently has version v7.10.1.

2 Likes

I messed up some dependency update. I want to keep it compatible to node6, and the server code is in typescript compiled for es5. Let me check.

It was more painful than I thought, but elm-doc-preview@3.0.0-rc3 has been released as elm-doc-preview@next and should be compatible with nodejs 6.17.1 and later.

1 Like

rc4 (@next) fixes a ws dependency issue with rc3, reintroduces markdown links without reloads from 2.x.x and redirects https://packages.elm-lang.org/packages/ links to relative /packages/ ones.

This will most likely be the last release candidate unless some new issues are found.

elm-doc-preview@3.0.0 has been released, thank you for all the feedback:

npm install -g elm-doc-preview

As an example of an Application documentation, you can browse the minimal elm-spa-example documentation generated with it (I have just added all exposed symbols in the documentation, but ideally most of them should be better documented):

https://elm-doc-preview.netlify.com/?repo=rlefevre/elm-spa-example

The online viewer is still based on version 2.x.x though and has a lot less features than the npm package. To get the same documentation locally with all the last features:

git clone https://github.com/rlefevre/elm-spa-example
cd elm-spa-example
npm i elm-doc-preview
npx elm-doc-preview
2 Likes

Application documentation is a fantastic addition. I just updated the application I’m currently developing to expose the little documentation it has and it complained repeatedly about exposing stuff that had no documentation, which not only forced me to write my docs but made me think about the interface that my modules expose! This will be so useful when I’m updating the application in the future, so thanks! :+1:

2 Likes

Thanks for the feedback, it’s greatly appreciated.

As Evan said:

I believe it is not available with "application" for now since they can benefit from having different rules. For example, in a professional setting, I have observed that making doc comments mandatory leads to a lot of {-|-} placed around. So it seems like it’d be valuable to allow partial documentation in this context.

elm-application.json exposed-modules allow to select which module is documented, but this might not be the perfect solution yet.

I still think it’s worth it to help newcomers with an application source code, to force documenting forked and private packages, and indeed to force developers to take care of the APIs and their documentation. The feedback about this solution might also help designing the official application solution that could be added in elm later.

1 Like

I still think it’s worth it to help newcomers with an application source code, to force documenting forked and private packages, and indeed to force developers to take care of the documentation. The feedback about this solution might also help designing the official application solution that could be added in elm later.

Yes, I totally agree with this. One of the big strengths of Rust is that it is easy to build the documentation for your module or application out of the box using cargo, and the Rust book encourages you to do this, so it’s something that I just started doing when I was first learning the language, then kept on doing. I opened an issue on the create-elm-app repo, because I think that application documentation with elm-doc-preview is a sensible default.

1 Like

Note that a simple JavaScript API is provided that might help integrating it in others projects.

1 Like

I get this error when I try to run elm-doc-preview for an application:

   unsupported Elm version 0.18.0

Yes, sorry, but elm < 0.19 is not supported.

There are too much changes in the documentation and packages format between 0.18 and 0.19.

Ah yes, but I am not using 0.18!

From the directory where you ran elm-doc-preview or the one you passed as argument, elm-doc-preview will run the following commands in this order:

  1. npx --no-install elm --version
  2. elm --version

For the first one that succeeds, elm-doc-preview will check that the version starts with 0.19.

In your case, the elm command that elm-doc-preview runs return a 0.18.0 version.

  • What do you get by running the above commands?
  • How do you run elm in your application?

Sorry, I’m traveling, so a bit slow to respond. Here is what I found:

 $ edp
unsupported Elm version 0.18.0
 $ npx --no-install elm --version
0.18.0
 $ elm --version
0.19.0
 $ cat make.sh
elm make --optimize src/NetworkSimulator.elm --output=NetworkSimulator.js

The npx output must be the culprit, but I don’t understand what is going on.

1 Like

You just have a 0.18 version installed locally in your project. You should see it in your package.json npm file:

"elm": "^0.18.0"

If you see it, remove it by running inside the project directory:

$ npm remove --save-dev elm

or upgrade it to 0.19:

$ npm install --save-dev elm@0.19.0

If it is not listed in your package.json or your don’t have such a file:

$ npm remove elm

This won’t remove your globally installed elm version.

Have a nice trip.

I cant seem to find a package.json:

 $ tree . | grep json
├── elm-application.json
│               ├── elm.json
├── elm.json
│   ├── elm.json

or anything with 0.18:

 $ grep -r "0.18.0" *
Binary file Simulator_report.pages.pdf matches

re trip: Thanks!!

PS. Some other searches:

$ grep -r "18" * | grep "json"
 $ grep -r "19" * | grep "json"
Main.js:	elm$json$Json$Decode$succeed(_Utils_Tuple0))({"versions":{"elm":"0.19.0"},"types":{"message":"Main.Msg","aliases":{"Graph.NodeId":{"args":[],"type":"Basics.Int"}},"unions":{"Main.Msg":{"args":[],"tags":{"DragStart":["Graph.NodeId","( Basics.Float, Basics.Float )"],"MouseClick":["Graph.NodeId","( Basics.Float, Basics.Float )"],"DragAt":["( Basics.Float, Basics.Float )"],"DragEnd":["( Basics.Float, Basics.Float )"],"Tick":["Time.Posix"],"GameTick":["Time.Posix"],"SetGraphBehavior":["Main.GraphBehavior"],"ReHeat":[],"AdvanceGameState":[],"GetRandomNumbers":[],"GotRandomNumbers":["List.List Basics.Float"],"SetDisplayMode":["Main.DisplayMode"],"CellGrid":["CellGrid.Msg"]}},"CellGrid.Msg":{"args":[],"tags":{"MouseClick":["( Basics.Int, Basics.Int )","( Basics.Float, Basics.Float )"]}},"Main.DisplayMode":{"args":[],"tags":{"DisplayGraph":[],"DisplayGrid":[]}},"Main.GraphBehavior":{"args":[],"tags":{"Selectable":[],"Draggable":[]}},"Basics.Float":{"args":[],"tags":{"Float":[]}},"Basics.Int":{"args":[],"tags":{"Int":[]}},"List.List":{"args":["a"],"tags":{}},"Time.Posix":{"args":[],"tags":{"Posix":["Basics.Int"]}}}}})}});}(this));
elm-stuff/generated-code/elm-explorations/test/elm.json:    "elm-version": "0.19.0",
elm.json:    "elm-version": "0.19.0",
heatFlow/elm.json:    "elm-version": "0.19.0",