Documentation generation

We are using Documenter.jl to generate the documentation web site based on markdown files stored in docs/src. Please help keeping the documentation up-to-date by editing the markdown files! For instructions on how to write appropriate documentation please refer to the relevant chapter in the Julia documentation and the Documenter.jl documentation.

Generating the documentation web site

The documentation pages can be generated by running the build script by typing

Rimu$ julia --project=docs docs/make.jl

on the shell prompt from the Rimu/ folder. A complete image of the static documentation web site will be generated in the folder docs/build/. It can be viewed locally by pointing a web browser to file docs/build/index.html, or by deploying it to the GitHub pages web server.

Automatic documentation generation and deployment

Our documentation is hosted on GitHub pages. The documentation web site can be built and deployed automatically with GitHub Actions. This needs to be set up with an appropriate script in the file .github/workflows/docs.yml, where triggers for this to happen can be defined. In the current set up, a new documentation web site is generated and deployed whenever someone pushes to the develop branch on the GitHub server. The updated documentation can then be accessed here.

Previews for pull-requests can be accessed by replacing 101 in the following link with the PR number: https://joachimbrand.github.io/Rimu.jl/previews/PR101/

Example scripts

Examples should be added to the scripts folder, in the form of .jl files suitable for parsing by Literate. The process of generating documentation is automated in the docs/make.jl file and assumes that the following line is at (or near) the top of the script:

# # Example N: Title

where the number N and Title will be extracted automatically.

Tests for the results and output of specific scripts should be added at the end of each example. The code to run the test should be hidden from the final generated document by appending "#hide" to each line of testing code. For example,

using Test                          #hide
@test isfile("result.out")          #hide
@test result == expected_result     #hide