Creating and updating PALEO documentation

Structure of PALEO documentation

Each PALEO repository follows the same structure and uses the same tools, just with different content.

PALEO documentation broadly follows the four-way split into tutorials, how-to guides, technical reference and explanation proposed by Divio

The PALEO-specific version of this is:

Tutorials -> Examples (collated from README.md in subfolders under ./examples/ or ./PALEOexamples/)
HOWTO guides -> HOWTOS (markdown documents in docs/src/ with HOWTO prefix)
Explanation -> Design (markdown documents in docs/src/ eg https://paleotoolkit.github.io/PALEOboxes.jl/stable/DesignOverview/)
Reference -> Reference (markdown document(s) in docs/src/ with a hand-crafted structure and most of the text autogenerated from docstrings in the Julia code)

Tools for PALEO documentation

The overall principle here is keep documentation minimal, and avoid duplication (which just rapidly goes out of date).

The documentation is created by the Julia Documenter.jl package, from scripts and markdown documents in the ./docs/ folder.

./docs/make.jl specifies the structure, and the markdown files to include.
./docs/src/ contains the documentation source files in Markdown
./docs/src/paleo_references.bib is a (hand-generated) bibtex bibliography, used by DocumenterCitations.jl to provide citations.
code is documented using Julia docstrings, see the documentation section in the Julia manual.

Creating and viewing documentation locally

activate the ./docs/ environment (eg right click in VS code)
change directory to the ./docs/ folder
julia> include("make.jl")

Output is created in the ./docs/build/ folder, index.html in this folder is the top of the html documentation tree.

There are two options to view this locally in a web browser:

Navigate to ./docs/build/ in a file browser, and click on index.html.
Install the VS Code Liveserver plugin, and right-click in the VS code file browser and select Open with Live Server

Publishing documentation on github

The public PALEO repositories (eg PALEOcopse) include a github workflow file (in .github/workflows/documentation.yml) that runs the build process on github, and then publishes the output to github pages. This runs automatically when a new release is created.

Adding a new top-level document

Create a new markdown file in the ./docs/ subfolder.
Update ./docs/make.jl to add this file at the relevant point in the documentation tree

Documenting PALEO code

Code eg PALEO reactions is documented using Julia docstrings, see the documentation section in the Julia manual.

There are then two parts to this:

Add docstrings in the .jl code files. There are some PALEO-specific extensions implemented to make it easy to document PALEO reaction Parameters and Variables, each module should contain using PALEOboxes.DocStrings to make these available. The docstring can then contain:
```
 # Parameters
 $(PARS)

 # Methods and Variables
 $(METHODS_DO)
```
which will automatically generate documentation from the description and units fields.
Update the top-level Reference documentation (markdown file(s) under ./docs) to include the new Reactions etc. This will expand into the docstring content.

Documenting PALEO examples

The mimimal, lightweight approach to documenting examples is to add a README.md to the subfolder. Suggest think of this like a lab book.

This can then be used in multiple ways:

view locally, either as raw markdown, or use VS code to render a preview (right click on the .md file).
github will show a README.md by default when you browse to that folder on github.com
the top-level documentation build script automatically collates all markdown documents it finds in examples subfolders into a browseable tree on the documentation web pages.

It is straightforward to add images to the README.md:

create an images/ subfolder
save images into this folder (.svg or .png)
add a link in the README.md eg ![Modern Earth sensitivity study](images/modEarth_compare.png)

NB: please check file sizes, and think whether the extra size in the PALEO repository is justitifed...

Adding "online" scripts and output

The PALEOtutorials repository exploits Documenter.jl syntax to add additional information in the README.md files to show the contents of files, and to run scripts and include text output and plots in the published web pages.

Examples from PALEOtutorials:

To show the content of files in a block in the rendered output:

```@eval
import Markdown
Markdown.parse(
    """```julia
    $(read(joinpath(ENV["PALEO_EXAMPLES"], "ocean_chemistry/run_ex2.jl"), String))
    ```"""
)
```

NB: the ENV["PALEO_EXAMPLES"] prefix to the path added with joinpath is key here, where ENV["PALEO_EXAMPLES"] defines the full path to the examples/ folder. To read and display just part of a file, use:

```@eval
import Markdown
Markdown.parse(
    """```julia
    $(join(readlines(joinpath(ENV["PALEO_EXAMPLES"], "ocean_chemistry/config_ex1.yaml"); keep=true)[5:19]))  # only lines 5:19 from config_ex1.yaml
    ```"""
)
```

To run a script and include output and figures:

```@example ex2
include(joinpath(ENV["PALEO_EXAMPLES"], "ocean_chemistry/run_ex2.jl")) # hide
plot(paleorun.output, ["ocean.TAlk_conc", "ocean.DIC_conc"], (cell=1,); ylabel="TAlk, DIC conc (mol m-3)") # hide
savefig("ex2_plot1.svg"); nothing  # hide
plot(paleorun.output, "ocean.pH", (cell=1,)) # hide
savefig("ex2_plot2.svg"); nothing  # hide
plot(paleorun.output, ["ocean.DIC_conc", "ocean.HCO3_conc", "ocean.CO3_conc", "ocean.CO2_aq_conc"], (cell=1,); ylabel="DIC species (mol m-3)") # hide
savefig("ex2_plot3.svg"); nothing  # hide
display(plot(paleorun.output, "atm.pCO2atm"))  # hide
savefig("ex2_plot4.svg"); nothing  # hide
display(plot(paleorun.output, ["global.C_total", "atm.CO2", "ocean.DIC_total"]; ylabel="atm-ocean carbon (mol)"))
savefig("ex2_plot5.svg"); nothing  # hide
```

![](ex2_plot1.svg)
![](ex2_plot2.svg)
![](ex2_plot3.svg)
![](ex2_plot4.svg)
![](ex2_plot5.svg)

NB: to include plots produced by a script whilst keeping the script useful for interactive use, the plotting code has been duplicated in the .md file with additional options to save the figures to .svg files.

NB: if new code files defining PALEO reactions are required, create a doc_include.jl as described below.

To make new code files available to document code using docstrings and to make new PALEO reactions available for use in runnable scripts: create a doc_include.jl file in the example subfolder, which contains include("my_new_code_file.jl") for each code file with new Reactions etc.