Skip to content

Documentation

DocStringExtensions.jl makes it easier to write docs. In particular, function signatures are automatically created in docstrings.

Literate.jl is useful for generating examples.

A useful guide to writing documentation (pointed out by Tim Holy on Discourse).

Useful for making tutorials:

Documenter.jl

Documenter.jl is the most commonly used package to write documentation.

Documentation specific dependencies are in ./docs/Project.toml. In my case, this contains FilesLH for deploying the docs. Then ./docs/make.jl needs to be called when the docs environment is active. Easiest: add Pkg.activate("./docs") at the start of make.jl and Pkg.activate(".") at the end.

It is then not necessary to have Documenter.jl as a dependency of the package.

All markdown files in the docs/src directory (and its subdirectories) are processed, even if they are not used in the docs.

Deploying (1.5)

The standard approach is TravisCI. Since I have private repos and a private package registry, I prefer “manual” hosting on my own website. I run the docs/make.jl documenation build script as usual, but replace deploydocs with FilesLH.deploy_docs. This simply rsyncs the static html files generated by Documenter.jl to my personal website.

See also Deploy Documenter docs locally.