Package: elm-doc
elm-docGenerate 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.18elm-doc version >= 1.0.0: Elm 0.19You will need to enable the--preflag if you're installing the latest version through thepipcommand.UsageSimplest 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 usespark:$ (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-docat the root of the project.
You may want to ignore it in your SCM config, or you can change its path with--build-dir.--validatecan check if you have all the necessary documentation in place:$ elm-doc . \
    --elm-path ./node_modules/.bin/elm \
    --validateelm-docassumes 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-modulesby usingfnmatchpatterns:$ elm-doc . --output docs --fake-license 'SPDX license name' \
    --exclude-modules '*.Private.*,Blacklist.*'or--exclude-source-directoriesentirely:$ elm-doc . --output docs --fake-license 'SPDX license name' \
    --exclude-source-directories generatedYou can also specify which files and directories toincludein the list of modules:$ elm-doc . --output docs \
    src/Whitelist src/Main.elmNote that the--excludeflag takes no effect if you explicitly specify which
files to include, unless you add the--force-exclusionflag:$ elm-doc . --output docs --fake-license 'SPDX license name' \
    --exclude-modules '*.Private.*,Blacklist.*' \
    --force-exclusion \
    src/Whitelist src/Main.elmFor a full list of options, see:$ elm-doc --helpInstallationIn a Python (>=3.5)virtualenvor globally:$ pip install --upgrade pip setuptools
$ pip install elm-docHow it worksThis is the rough build process:Generate a temporary elm.json file in the build directoryChange the type topackageand restructure / reformat to match the schema for a package project's elm.jsonPopulate--fake-*fields, including the license: these are required for a package project but not included in an application project's elm.jsonAdd dependencies that are listed as popular packages in the sidebar, making HTTP requests to look up the latest versionsThis means the actual build / validation process will have its own elm-stuff directoryCopy source files into the build directory'ssrcdirectory using rsyncAn application project supports multiple source directories, while a package project supports onlysrcFor each file that was copied, rewrite port delcarations to be normal functionsThis is needed because ports are not allowed in package projectsRunelm makewith the--docflag onIf validating docs, exit hereGenerate the top page of the package, individual module pages, and other files required for the package website to functionFor each dependency, copy docs.json from the per-user package cache. This is generally in~/.elmFor each dependency, also generate files required for the package website to functionGenerate site-wide search index in a JSON format that the frontend expectsGenerate help pages hosted by the package websiteExtract frontend code that is prebuilt and distributed as part of the elm-doc Python packageIt is aforkof the elm/package.elm-lang.org repo that takes a flag that specifies which URL path the frontend app is mounted atThese are all implemented asdoittasksDevelopmentRunning tests:$ nix-shell
$ poetry install
$ poetry run tox -e py35,...Updating the prebuilt frontend code and test fixture:$ poetry run doit