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

dmy · August 14, 2019, 4:48pm

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):

dmy · August 14, 2019, 11:30pm

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.

arowM · August 15, 2019, 7:04am

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.

dmy · August 15, 2019, 7:29am

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.

rupert · August 15, 2019, 9:22am

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.

dmy · August 15, 2019, 10:16am

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.

dmy · August 15, 2019, 12:41pm

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.

dmy · August 15, 2019, 11:54pm

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.

dmy · August 16, 2019, 11:23am

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

ChrisWellsWood · August 16, 2019, 1:55pm

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!

dmy · August 16, 2019, 2:06pm

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.

ChrisWellsWood · August 16, 2019, 2:51pm

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.

dmy · August 16, 2019, 3:06pm

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

jxxcarlson · August 18, 2019, 6:39am

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

   unsupported Elm version 0.18.0

dmy · August 18, 2019, 6:51am

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.

jxxcarlson · August 18, 2019, 8:30am

Ah yes, but I am not using 0.18!

dmy · August 18, 2019, 8:47am

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:

npx --no-install elm --version
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?

jxxcarlson · August 19, 2019, 5:16am

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.

dmy · August 19, 2019, 6:45am

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.

jxxcarlson · August 19, 2019, 7:01am

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",

Topic		Replies	Views
Elm-doc-preview update: hot reloading & previews sharing Show and Tell	2	896	December 24, 2018
Elm-doc-preview: A new online documentation previewer Show and Tell	5	2335	September 30, 2018
Docs preview 404s still in effect Learn	3	457	December 6, 2019
Current commonly used tool for previewing docs? Learn	5	465	October 26, 2023
Possible project: docs previewer Show and Tell	5	1391	March 28, 2018

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

Related topics