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.
“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
.
API
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();
FAQ
Is elm-doc-preview secure enough to publicly host documentation?
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).
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.
Credits
- 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.