Skip to content
Elm offline documentation previewer
Elm TypeScript CSS JavaScript Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
project-metadata-utils
screenshots
src
static
types/opn
.gitignore
.npmignore
LICENSE.md
Makefile
README.md
cli.js
elm-application.json
elm.json
package-lock.json
package.json
tsconfig.json

README.md

elm-doc-preview

This is an Elm 0.19 offline documentation previewer for packages, applications, their dependencies and all cached packages.

It aims at rendering documentation exactly like the official package website to avoid any surprise when releasing a package.

Features

  • Packages and Applications support with documentation hot reloading
  • Offline cached packages documentation server
  • Source and documentation compilation errors display
  • Online documentation sharing for reviews (using the online version)

elm-doc-preview

Installation

$ npm install -g elm-doc-preview

Synopsis

Usage: edp|elm-doc-preview [options] [path_to_package_or_application]

Options:
  -V, --version      output the version number
  -p, --port <port>  the server listening port (default: 8000)
  -n, --no-browser   do not open in browser when server starts
  -h, --help         output usage information

Environment variables:
  ELM_HOME           Elm home directory (cache)

For example, from the directory where your project elm.json is:

$ elm-doc-preview

or

$ edp

or from anywhere:

$ elm-doc-preview path/to/package_or_application

When no package or application is found, elm-doc-preview will just run as an offline documentation server for local cached packages.

Applications support

Application documentation is not yet supported by Elm, so elm-doc-preview will generate a package from the application with the same modules and build the documentation from it. There are two consequences:

  1. You have to define an elm-application.json file to list the application documented modules (exposed-modules) or to customize the application name, summary or version that are included in the documentation.
  2. The application ports will be stubbed with fake versions as ports are forbidden in packages. This means that ports will appear as normal functions in the documentation. Also currently, this requires ports declarations to be on one line, if this is an issue for you, please open an issue.

Without an elm-application.json file, elm-doc-preview will show an application as my/application 1.0.0 and will report an error about missing exposed-modules unless some are eventually found in forked or local packages included in the application source-directories.

To configure the application, add an elm-application.json file with at least an exposed-modules value.

For example, here is the elm-application.json file for the elm-doc-preview Elm application followed by a description of each field:

elm-application.json:

{
    "name": "dmy/elm-doc-preview",
    "summary": "Offline documentation previewer",
    "version": "3.0.0",
    "exposed-modules": [
        "Href",
        "Session",
        "Page.Docs.Block",
        "Page.Search",
        "Page.Diff",
        "Page.Problem",
        "Page.Docs",
        "Page.Search.Entry",
        "Release",
        "Utils.Spinner",
        "Utils.OneOrMore",
        "Utils.Logo",
        "Utils.Error",
        "Utils.Markdown",
        "Main",
        "Skeleton"
    ]
}

"name"

It should use the same author/project format than packages, but the repository does not have to exist on GitHub.

The default name is my/application.

"summary"

A short summary for the application in less than 80 characters.

The default summary is "Elm application".

"version"

A version using MAJOR.MINOR.PATCH format.

The default version is "1.0.0".

"exposed-modules"

The modules to include in the documentation. All exposed symbols inside these modules must be documented or the documentation build will fail.

Port modules will be shown as normal modules.

Exposed modules contain by default those found in forked and local packages (see next section). Setting the field does not remove those modules from the list.

Forked and local packages in applications

elm-doc-preview will automatically exposes documentation for forked or local packages modules if their are exposed in an elm.json file located in the directory above the one declared in source-directories.

Typically, to import a forked package and keep its documentation, just clone it in the application directory, and add the forked packages src sub-directory in elm.json source-directories.

See the project-metadata-utils fork inside elm-doc-preview for an example.

Online version

There is also an online version supporting documentations loading from github to share them for online reviews:

https://elm-doc-preview.netlify.com

It does not support hot-reloading or dependencies documentation though.

API

const DocServer = require('elm-doc-preview');

// constructor(elm_json_dir = ".")
const server = new DocServer();

// Optionally exit cleanly on SIGINT
process.on("SIGINT", () => process.exit(0));

// listen(port = 8000, browser=true)
server.listen();

FAQ

Why adding elm-application.json instead of using elm.json?

Extending elm.json would not be convenient because elm install will remove any unexpected field from it when run, and all the additional fields used by elm-doc-preview are currently unexpected for an application, even if they are valid for a package.

Why my forked/local/vendored packages modules are not automatically documented?

They are automatically added in the documentation if you kept the package elm.json file in the directory above the package src one.

How do I get my application docs.json file?

By default, you can get your application docs.json file at the following address:

http://localhost:8000/packages/my/application/1.0.0/docs.json

If you added an elm-application.json file, replace my/application and 1.0.0 by the name and version fields value.

Also replace 8000 by the port used if you changed it.

How to generate static web pages of the documentation

This is not supported by elm-doc-preview, you could use ento/elm-doc instead.

Credits

You can’t perform that action at this time.