elm-doc
Generate static documentation of your Elm application project.
Requires Python >= 3.5, rsync >= 2.6.7, and macOS or Linux. It may work on Windows but it's untested.
Supported Elm versions:
- elm-doc version < 1.0: Elm 0.18
- elm-doc version >= 1.0.0: Elm 0.19
You will need to enable the --pre
flag if you're installing the latest version through the pip
command.
Usage
Simplest invocation:
$ elm-doc . --output docs --fake-license 'SPDX license name'
The license name is required because elm-doc uses the official Elm binary to validate and generate docs; the official Elm binary only generates docs for a package project, and a package project requires a license to be set. While the license name will not be part of the generated doc, it will be associated with the project in the temporary elm.json file elm-doc generates during the build / validation.
Do no use elm-doc if you'd rather not risk the legal consequences of this fact. (IANAL: my understanding is OSS license doesn't take effect unless you distribute the code it's attached to.)
To view the generated docs, you'll need an HTTP server that can detect mimetypes based on file contents, rather than file extensions.
I personally use spark:
$ (cd doc && ~/go/bin/spark)
You can specify other attributes of the project with --fake-user
, --fake-project
,
and --fake-version
.
elm-doc creates a build directory named .elm-doc
at the root of the project.
You may want to ignore it in your SCM config, or you can change its path with --build-dir
.
--validate
can check if you have all the necessary documentation in place:
$ elm-doc . \
--elm-path ./node_modules/.bin/elm \
--validate
elm-doc
assumes you're working on an app, not a package; it will try to generate
documentation for all modules found in the application source directories.
You can --exclude-modules
by using fnmatch
patterns:
$ elm-doc . --output docs --fake-license 'SPDX license name' \
--exclude-modules '*.Private.*,Blacklist.*'
or --exclude-source-directories
entirely:
$ elm-doc . --output docs --fake-license 'SPDX license name' \
--exclude-source-directories generated
You can also specify which files and directories to include in the list of modules:
$ elm-doc . --output docs \
src/Whitelist src/Main.elm
Note that the --exclude
flag takes no effect if you explicitly specify which
files to include, unless you add the --force-exclusion
flag:
$ elm-doc . --output docs --fake-license 'SPDX license name' \
--exclude-modules '*.Private.*,Blacklist.*' \
--force-exclusion \
src/Whitelist src/Main.elm
For a full list of options, see:
$ elm-doc --help
Installation
In a Python (>=3.5) virtualenv or globally:
$ pip install --upgrade pip setuptools
$ pip install elm-doc
How it works
This is the rough build process:
- Generate a temporary elm.json file in the build directory
- Change the type to
package
and restructure / reformat to match the schema for a package project's elm.json - Populate
--fake-*
fields, including the license: these are required for a package project but not included in an application project's elm.json - Add dependencies that are listed as popular packages in the sidebar, making HTTP requests to look up the latest versions
- This means the actual build / validation process will have its own elm-stuff directory
- Change the type to
- Copy source files into the build directory's
src
directory using rsync- An application project supports multiple source directories, while a package project supports only
src
- An application project supports multiple source directories, while a package project supports only
- For each file that was copied, rewrite port delcarations to be normal functions
- This is needed because ports are not allowed in package projects
- Run
elm make
with the--doc
flag on - If validating docs, exit here
- Generate the top page of the package, individual module pages, and other files required for the package website to function
- For each dependency, copy docs.json from the per-user package cache. This is generally in
~/.elm
- For each dependency, also generate files required for the package website to function
- Generate site-wide search index in a JSON format that the frontend expects
- Generate help pages hosted by the package website
- Extract frontend code that is prebuilt and distributed as part of the elm-doc Python package
- It is a fork of the elm/package.elm-lang.org repo that takes a flag that specifies which URL path the frontend app is mounted at
- These are all implemented as doit tasks
Development
Running tests:
$ nix-shell
$ poetry install
$ poetry run tox -e py35,...
Updating the prebuilt frontend code and test fixture:
$ poetry run doit