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.