dmy / elm-doc-preview Goto Github PK

When running

$ npm install -g elm-doc-preview

npm complains:

npm WARN [email protected] requires a peer of bufferutil@^4.0.1 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of utf-8-validate@^5.0.2 but none is installed. You must install peer dependencies yourself.

I then installed those two, but even after that I still get same warnings:

$ npm install -g bufferutil@^4.0.1
$ npm install -g utf-8-validate@^5.0.2
$ npm install -g elm-doc-preview
npm WARN [email protected] requires a peer of bufferutil@^4.0.1 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of utf-8-validate@^5.0.2 but none is installed. You must install peer dependencies yourself.

elm-doc-preview seems to at least start, so I'm not sure if this is a problem or not.

I'm using elm-doc-preview to generate application documentation, and would love a way to verify that my documentation is valid in CI. Just elm make --docs (per #23 and #21) doesn't seem to work to verify documentation correctness (or even to generate docs at all), which I assume is expected, given that my Elm code is an app and not a package.

Also, thank you for this awesome package!

Following from the discussion here:

a nice default for the name would be user_name/dir where dir is the name of the directory containing the elm.json file, as I think this directory is usually a kind of project name

@rlefevre replied with:

The potential issue with that is that sometimes the elm app is in a sub-directory of the project. For example, for one of my Elixir/Phoenix app, the elm application is in assets/elm, so the application would be named my/elm

Thinking about this, maybe if the default is no good you would then specify the name in the application.json? I'm just trying to think of what happens in the majority of cases. I think most of the time the elm.json file sits in the root directory which has a kind of application name. But I think we probably need more opinions here.

Also from @rlefevre:

Another issue is that there are a lot more restrictions on package names that directory names (and the application is transformed to a package before generating the documentation). A lot of characters are forbidden, and a few more rules.

Perhaps we could transform the directory name into something friendly?

If I make changes to my documentation and then "Close Preview", "Open Files" doesn't work again until the page is refreshed.

When I'm working on my own documentation, I often browse through the docs using elm-doc-preview, see something I want to change, make the edit and save the Elm file. This causes a hot reload of the documentation, which is great, but also causes the page to scroll back to the top and I have to scroll down to get back to where I was (unless I get clever and click the current function name first, so that it becomes the hash value in the URL and therefore causes the browser to scroll back to the function after reloading). Would it be possible to add some logic to maintain the scroll position after a hot reload?

First, thank you for this project, I love being able to browse the docs for our application!

I ran into an issue where when we have some files with incorrect or missing documentation, edp doesn't list the errors that need to be fixed in the documentation.

In our case it was failed to parse the string that comes back from running elm make

 |> stubbing incoming port uiVideoPlayerInbound
  |> stubbing outgoing port uiVideoPlayerOutbound
SyntaxError: Unexpected token n in JSON at position 1899
  |> writing documentation into docs.json
failed to build project documentation

I added some additional logging and it looks like this line is where it is happening: https://github.com/dmy/elm-doc-preview/blob/master/lib/elm-doc-server.ts#L328

In the output in ends up getting something like

{"type":"compile-errors","errors":[....the rest of the error json}npm ERR! code 1
npm ERR! path /Users/user/path/to/project/elm-stuff/elm-application-482575LMmitR960sw
npm ERR! command failed
npm ERR! command sh -c elm "make" "--docs=/var/folders/h5/nv96dt4j2rs9rhh4zxq4gjjw0000gn/T/elm-docs-48257qjjrw5ZuSXCo.json" "--report=json"
npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/user/.npm/_logs/2021-03-09T14_51_44_781Z-debug.log

It is those additional npm ERR! strings that cause the parsing to fail, I tweaked the code on that line to strip out anything after npm ERR!, and that seems to solve it.

    let replacedStr = build.stderr.toString().replace(/npm ERR! .*/gm, "");
    elmErrors(JSON.parse(replacedStr));

node version: v15.1.0
npm version: 7.5.2
OS: MacOS Catalina 10.15.7

Promise error when checking for new versions is not caught, leading to an exception.

We could use Hugo templates to avoid duplicate html between index.html, noindex.html and local.html as it is supported by netlify.

It appears the following line is assuming too much about the location of elm.json, and thus misses exposed modules in a lot of situation.

It is currently possible to browse manually a locally cached package documentation:

$ elm-doc-preview ~/.elm/0.19.0/package/elm/html/1.0.0/

However as the local cache contains each dependency once elm make has been run, it could be possible to allow to browse offline the package dependencies documentation directly from the web interface.

Once this is done, support to browse an application dependencies documentation could eventually be added.

I currently have a submodules folder on the same level of the src directory that has modules I need to import for components in the src directory, but this is throwing the 'When creating a package, all modules must live in the src/ directory.' error. Is this something that you will be able to fix?

This looks really useful. I would enjoy a local version via e. g. an npm package. I imagine it working by executing something like npx elm-doc-preview in the repository and it starting a server that I can access in my browser and that hot-reloads (#4) whenever I change my files.

I would prefer this over the online service, because I just want a quick preview. Running one command in the folder seems even simpler than importing files (that I would need to manually generate) into a website.

I don't know whether I can invest the time to open a PR for this, but I still want to pitch the idea.

Hi!

First of all, thanks for the awesome tool, I find it really useful!

One of the things I like about this tool, is that it tells us when the documentation is incomplete or erroneous, and it does that before we'd try to publish the package.

What I would like, is a way to enforce that the documentation is complete and valid when running the test suite. This way, when someone makes a pull request to your project, you don't have to manually run elm-doc-preview to verify that the docs are still okay. I think this can be especially useful for package repositories.

My proposal is to add a --check (or similarly named) option that doesn't run the documentation server, and only checks whether the docs are valid. If they are, the process succeeds, otherwise the process fails and the same errors as in the server are shown in the terminal.

Let me know what you think :)

The websocket connection status is not checked before sending messages.
Consequently we may try to send some messages on a disconnected web socket, leading to the exception.

I really love this tool!

For documenting an internal application, it would be easiest if we could generate the documentation as a static site we could deploy on our intranet, so that anyone can easily read the documentation. Would this be possible?

I am getting this error:

 $ elm-doc-preview
elm-doc-preview 3.0.4 using elm 0.19.1
Previewing jxxcarlson/elm-typed-time 1.0.0 from /Users/carlson/dev/elm/projects/typed-time
Browse <http://localhost:8000> to see your documentation
  |> watching package
  |> building /Users/carlson/dev/elm/projects/typed-time documentation
TypeError: Cannot read property 'length' of null

This error occurs within 15 seconds of starting elm-doc-preview. Could something be wroing with one of my files?

Would it be possible to change the previewer to use the same URL scheme as package.elm-lang.org? For example, currently a module Nested.Module will have the path #/Nested.Module in the previewer where the official package site would use Nested-Module.

Making this change would presumably also allow putting anchors on individual types/functions/values, also to match the official package site (so that Nested.Module.foo would have the path Nested-Module#foo). Having both would mean that Markdown links to other functions/values/types in the same package would work the same way in the previewer as on the official package site, which would be very useful to be able to check.

Links added in some markdown as [Module](/Module) won't work in the final documentation because they will point to https://package.elm-lang.org/Module instead of https://package.elm-lang.org/packages/author/package/Module but they will work in the preview as the module is the only path segment there.

The correct way to link to another module that will work in both the final documentation and the preview is to use:

• [Module](Module)
• or [Module](./Module) to avoid elm-format bug avh4/elm-format#339 (comment)
• or [Module.function](Module#function)
• or [Module.SubModule.function](Module-SubModule#function)

A warning should be added when clicking such broken links in the preview to allow the editor to fix them.

It should be possible to browse the source of local packages.

Hi, I've been running elm-doc-preview on this project. The READEM.md file shows up, but no documentation for modules -- they are not listed in the usual place on the right. Attached is my elm.json file, and below that is the output edp -d. Thanks!

{
    "type": "package",
    "name": "jxxcarlson/minilatex-b",
    "summary": "Compile MiniLaTeX to Html",
    "license": "MIT",
    "version": "1.0.0",
    "exposed-modules": [
        "Compiler.LaTeXData"
    ],
    "elm-version": "0.19.0 <= v < 0.20.0",
    "dependencies": {
        "elm/core": "1.0.0 <= v < 2.0.0",
        "elm/html": "1.0.0 <= v < 2.0.0",
        "elm/json": "1.1.3 <= v < 2.0.0",
        "elm/parser": "1.1.0 <= v < 2.0.0",
        "elm-community/list-extra": "8.3.0 <= v < 9.0.0",
        "elm-community/maybe-extra": "5.2.0 <= v < 6.0.0",
        "elm-explorations/test": "1.2.2 <= v < 2.0.0",
        "folkertdev/elm-paragraph": "1.0.0 <= v < 2.0.0"
    },
    "test-dependencies": {}
}

Terminal session:

➜  minilatex-b git:(master) edp -d
elm-doc-preview 5.0.5 using elm 0.19.1
Previewing jxxcarlson/minilatex-b 1.0.0 from /Users/carlson/dev/brilliant/minilatex-b
Browse <http://localhost:8000> to see your documentation
  |> watching package
{
  '/Users/carlson/dev/brilliant/minilatex-b': [ 'README.md', 'elm-tooling.json', 'elm.json' ],
  '/Users/carlson/dev/brilliant/minilatex-b/src': [ 'CommandInterpreter.elm', 'Utility.elm' ],
  '/Users/carlson/dev/brilliant/minilatex-b/src/Render': [ 'LaTeXState.elm', 'Render.elm' ],
  '/Users/carlson/dev/brilliant/minilatex-b/src/Parser': [
    'Block.elm',
    'Document.elm',
    'Expression.elm',
    'Helpers.elm',
    'Parser.elm',
    'Problem.elm',
    'TestData.elm',
    'TestHelper.elm',
    'TextCursor.elm'
  ],
  '/Users/carlson/dev/brilliant/minilatex-b/src/Compiler': [ 'Differ.elm', 'GenericDiffer.elm', 'LaTeXData.elm' ]
}
  |> ::1 connected
  |> building /Users/carlson/dev/brilliant/minilatex-b documentation
  |> generating /var/folders/ml/vl09g4313rb1jd6y9zvcd6200000gn/T/elm-docs-23433a7OntyQNkWYi.json documentation

To avoid users missing new features, a discreet warning could be displayed on start to inform about a new release being available.

This should not lead to an error when offline.

I'm currently using (or rather misusing) elm-doc-preview to generate a docs.json for my application, using an elm-application.json as suggested in the README. I'm starting up elm-doc-preview for the sole purpose of generating the docs.json file, retrieving it with curl and then stopping the server again. This doesn't play well with build scripts, and I would like elm-doc-preview to have a CLI flag that does this:

• Generate docs.json and write it to file
• Exit with 0 if it succeeds or something else if the docs.json couldn't be generated.

Thanks for making this useful tool! 😊

As far as I can tell the server currently binds to all IPs, which means that its contents may be accessible from a machine on the local network, which may or may not be wanted.

Would you be open to making the binding address configurable? Ideally this would default to the loopback address (127.0.0.1), though this behaviour may be considered a breaking change for existing users.

It could work like this:

$ elm-doc-preview # server only listens on 127.0.0.1:8000
$ elm-doc-preview --address 192.178.0.100 --port 9090 # server only listens on 192.178.0.100:9090
$ elm-doc-preview --address 0.0.0.0 # server listens on all IPs on port 8000

Would you be interested in a PR? Is a breaking change acceptable?

This happens when clicking a dependency package and is due to the manual handling of anchors clicks in javascript (to workaround markdown limitations).

I don't think that this has some effect beside the error log.

I installed elm-doc-preview on Windows 10 with

npm install -g elm-doc-preview

When trying to run in a package directory I get the following error message:

c:\Git\ianmackenzie\elm-units>elm-doc-preview
Error: unsupported Elm version null
0.19.0

c:\Git\ianmackenzie\elm-units>elm --version
0.19.0

If it makes a difference, I installed Elm itself using the Windows installer, not via NPM - so it's on my PATH, but if elm-doc-preview is looking for it specifically in some Node directories then it won't find it.

Hi,

I have elm-doc-preview in my package.json's devDependencies. It's really cool to use :-) However, since I added it, github and npm complain about vulnerabilities.

Would be nice if they could be fixed. Maybe running npm audit fix will be enough. If not it would require manual review.

This error is due to the following elm compiler bug: elm/compiler#1836 and will be fixed in next Elm release.

As far as I can tell, it has no consequence except the error log for elm-doc-preview.

This is an awesome tool. If I have a huge elm application it can help me understand the project much easier, so I thank you for this.

If there are many modules in an application, it can be a pain adding these to exposed modules and maintaining this list whenever modules are added/removed. All I really want to do is browse all modules in source-directories specified in the elm.json. Would it be possible for this to be the default behaviour when no elm-application.json is present, rather than reporting an error?

Otherwise I’m happy for this behaviour to be a switch in the elm-application.json.

Cheers

Hi there,

it works nicely. it looks very interesting too. thank you for providing this library.

regards

Ben

I ran into this when working on a new package of testing utilities for elm-geometry, where all the modules are simply copied over from elm-geometry using a script. Doing so seems to confuse elm-doc-preview if it's running a server at the time the files are copied over - one time it only noticed that one file had changed and so didn't update another, and another time the server crashed with

Error: EPERM: operation not permitted, lstat 'C:\Git\ianmackenzie\elm-geometry-test\rm-5'

Not a critical issue and probably a very rare use case, but I thought I'd mention it!

Depending on how much you can do with Netlify's free tier, it would be really cool to have a "get permalink" button which would save the currently displayed docs to some sort of storage, then provide a permalink so that anyone else can view that documentation. This would be really helpful for sharing documentation snapshots on Slack etc. to get feedback on in-progress packages; currently the best approach is to upload README.md and docs.json to Slack and have others upload those to the previewer themselves.

Online version at https://elm-doc-preview.netlify.app/ doesn't mention that this can be used for packages and applications.

I have a couple of forked packages in my application, it would be great if I could browse those as well. Is there an elm limitation or it's just not implemented yet?

If I run elm-doc-preview, it will successfully show me my package documentation but after about 30 seconds, it will crash and the documentation I was viewing will refresh and tell me the page failed to load.

C:\Users\Martin\Desktop\elm-codec-bytes>npx elm-doc-preview
elm-doc-preview 5.0.3 using elm 0.19.1
Previewing MartinSStewart/elm-serialize 1.0.0 from C:\Users\Martin\Desktop\elm-codec-bytes
Browse <http://localhost:8000> to see your documentation
  |> watching package
  |> building C:\Users\Martin\Desktop\elm-codec-bytes documentation
  |> detected src\Serialize.elm modification
  |> building C:\Users\Martin\Desktop\elm-codec-bytes documentation
  |> sending Docs
  |> building C:\Users\Martin\Desktop\elm-codec-bytes documentation
TypeError: Cannot read property 'length' of null

This is occurring on Windows 10 with Firefox. I haven't tested any other OS's or browsers.

Thank you for this useful tool! It is really designed in the spirit of Elm and helps guiding me through my documentation task.

Is there any way documentation comments for unexposed functions and types could be added to the generated documentation for applications? I realise this is not how it works on Elm Packages, but on the other hand applications aren't documented there at all.

Use case: I try to document an application for my colleagues, and I think they would appreciate being able to browse the complete documentation with elm-doc-preview. But as I've tried to only expose what is necessary, a large part of the application code is internal to the modules and much of the documentation comments I add doesn't show up in the preview.

Just reading the comments in the code is of course a valid work around, although not as pleasant.

Building applications documentation with nodejs < 12.x can fail with the following error:

Error: ENOENT: no such file or directory, mkdir ...

This is due to mkdirSync not supporting the recursive: true option in nodejs versions < 12.x.

I'd like to have my automated tests check that my docs are formatted well. If there are errors detected they're shown in the browser, and the checks done are more thorough than those done by the compiler. I'd like to be able to run the docs-previewer on the command line, see those errors there, and emit an exit code, without starting the webserver.