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.
- 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)
$ npm install -g elm-doc-preview
npm
may warn about missing peer dependencies:
npm WARN ws@7.2.3 requires a peer of bufferutil@^4.0.1 but none is installed. You must install peer dependencies yourself.
npm WARN ws@7.2.3 requires a peer of utf-8-validate@^5.0.2 but none is installed. You must install peer dependencies yourself.
They are optional, provide marginal websockets optimizations for elm-doc-preview
use case, and can be ignored.
Usage: edp|elm-doc-preview [options] [path_to_package_or_application]
Options:
-V, --version output the version number
-b, --no-browser do not open in browser when server starts
-d, --debug enable debug (display watched files and keep temporary files)
-o, --output <docs.json> generate docs and exit with status code (/dev/null supported)
-p, --port <port> the server listening port (default: 8000)
-r, --no-reload disable hot reloading
-h, --help display help for command
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.
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. By default:
- All modules in your
elm.json
source-directories
will be exposed - The application name will be
my/application
- The version will be
1.0.0
If you do not want all modules exposed, you have to define an elm-application.json
file to list the application
documented modules (exposed-modules). You may also customize the application
name, summary or version that are included in the documentation.
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": "5.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"
]
}
Property | Description | Default |
---|---|---|
name | It should use the same author/project format than packages, but the repository does not have to exist on GitHub. |
"my/application" |
summary | A short summary for the application in less than 80 characters | "Elm application" |
version | A version using MAJOR.MINOR.PATCH format |
"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. | Modules in the elm.json source-directories (overridable), and modules in forked and local packages (not overridable, see next section) |
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.
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
.
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.
const DocServer = require('elm-doc-preview');
const server = new DocServer();
server.listen();
or with custom options:
const DocServer = require('elm-doc-preview');
// constructor(options) {
// const {
// debug = false,
// dir = ".",
// port = 8000,
// browser = true,
// reload = true
// } = options || {};
// ...
const server = new DocServer({ port: 9000, browser: false });
server.listen();
elm-doc-preview
is a development tool and is not designed to be
exposed on internet. As such, no effort at all has been made to secure it
and it most likely contains severe vulnerabilities. If you want to
publicly share some documentation, use the online version or maybe host
static web pages of the documentation (see below).
This is not supported by elm-doc-preview
, you could use ento/elm-doc instead.
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.
They are automatically added in the documentation if you kept the package
elm.json
file in the directory above the package src
one.
- Documentation rendering from package.elm-lang.org by Evan Czaplicki.
- Markdown rendering from Marked.js by Christopher Jeffrey.
- Code highlighting from highlight.js by Ivan Sagalaev.
- Code highlighting theme from Solarized by Jeremy Hull.
- CSS spinner from SpinKit by Tobias Ahlin.
- Source Sans Pro and Source Code Pro fonts by Paul D. Hunt.