Merge pull request #32 from PALEOtoolkit/doc_update

Update documentation

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 PALEOaqchem = "673cec3b-17d1-411f-9fcd-71c01c593120"
 PALEOboxes = "804b410e-d900-4b2a-9ecd-f5a06d4c1fd4"
@@ -13,9 +14,9 @@ Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
 [compat]
 Documenter = "1"
 DocumenterCitations = "1"
+PALEOaqchem = "0.3.9"
 PALEOboxes = "0.21.23"
 PALEOmodel = "0.15.40"
-PALEOaqchem = "0.3.9"
 Revise = "3.1"
 julia = "1.6"
 

docs/make.jl

@@ -2,13 +2,26 @@ using Documenter
 
 using DocumenterCitations
 
+using DocumenterInterLinks
+
 import PALEOboxes as PB
 
 bib = CitationBibliography(
     joinpath(@__DIR__, "src/paleo_references.bib");
     style=:authoryear,
 )
 
+links = InterLinks(
+    "PALEOboxes" => (
+        "https://paleotoolkit.github.io/PALEOboxes.jl/stable/",
+        "https://paleotoolkit.github.io/PALEOboxes.jl/stable/objects.inv",
+    ),
+    "PALEOmodel" => (
+        "https://paleotoolkit.github.io/PALEOmodel.jl/stable/",
+        "https://paleotoolkit.github.io/PALEOmodel.jl/stable/objects.inv",
+    ),
+)
+
 # Collate all markdown files and images folders from PALEOexamples/src/ into a tree of pages
 ENV["PALEO_EXAMPLES"] = normpath(@__DIR__, "../examples") # make ENV["PALEO_EXAMPLES"] available in README.md etc
 io = IOBuffer()
@@ -32,8 +45,11 @@ makedocs(;
             "ExampleInstallConfig.md",
             examples_pages,
         ),
-        # no Design docs yet
+        "Design" => [
+            "ComponentsWorkflow.md",
+        ],
         "HOWTOS" => [
+            "HOWTOshowmodelandoutput.md",
             "HOWTOJuliaUsage.md",
             "HOWTOadditionalconfig.md",
             "HOWTOminimalGit.md",
@@ -47,7 +63,7 @@ makedocs(;
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true"
     ),
-    plugins = [bib],
+    plugins = [bib, links],
 )
 
 @info "Local html documentation is available at $(joinpath(@__DIR__, "build/index.html"))"

docs/src/ComponentsWorkflow.md

@@ -0,0 +1,3 @@
+# PALEOtoolkit components and workflow
+
+![image](images/PALEO_components_workflow.svg)

docs/src/HOWTOJuliaUsage.md

@@ -1,8 +1,7 @@
-# Julia usage
+# Julia and VS code usage
 
 ## Julia resources
-- Julia manual <https://docs.julialang.org/en/v1>
-- Think Julia book (an introduction to programming) <https://benlauwens.github.io/ThinkJulia.jl/latest/book.html>
+- Julia homepage <https://julialang.org/> (see links to `Documentation` and a curated list of tutorials, books, etc under `Learn`)
 - Julia cheatsheet: <https://juliadocs.github.io/Julia-Cheat-Sheet>
 - Matlab-Python-Julia cheatsheet: <https://cheatsheets.quantecon.org> (NB: the first example on Creating Vectors is misleading - use 1d Arrays in Julia!)
 
@@ -18,20 +17,27 @@ VS code has an option to automatically load Revise.jl at startup (enabled by def
 
 The Debugger.jl built in to VSCode is an interpreter (Interpreter.jl), and is unusably slow for PALEO.
 
+## Install the VS code yaml extension
+
+A VS code yaml extension is now available, https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml,
+this will flag errors in the PALEO yaml configuration files when opened in the VS code editor.
+
+NB: The Julia [YAML.jl](https://github.com/JuliaData/YAML.jl) parser allows duplicate keys (later key overwrites earlier) <https://github.com/PALEOtoolkit/PALEOboxes.jl/issues/43>. This is easy to hit when generating model configurations, the VS code yaml linter will catch this and other errors. If all else fails, check the .yaml file using an online validator eg <http://www.yamllint.com/>.
+
 ## Julia best practices
 - Performance tips: <https://docs.julialang.org/en/v1/manual/performance-tips/>
 - Julia antipatterns: <https://www.oxinabox.net/2020/04/19/Julia-Antipatterns.html>
 - Batch usage: <https://github.com/CliMA/ClimateMachine.jl/wiki/Caltech-Central-Cluster>
 
 ## Julia bugs/gotchas
-- [YAML.jl](https://github.com/JuliaData/YAML.jl) parser allows duplicate keys (later key overwrites earlier) TODO report. This is easy to hit when generating model configurations. Workaround: check the .yaml file using an online validator eg <http://www.yamllint.com/>.
 - Continuation lines in multi-line formulas can silently fail (this is easy to hit when copying across Fortran code). Workaround - add brackets.
 - Debug in VSCode is very slow. Use [Infiltrator.jl](https://github.com/JuliaDebug/Infiltrator.jl) instead.
 - Legends on subplots are merged with some backends eg plotlyjs (<https://github.com/JuliaPlots/Plots.jl/issues/673>). Workaround - use a different backend for multiple-panel plots.
 - [jldoctest](https://juliadocs.github.io/Documenter.jl/stable/man/doctests/) fails if there is an initial blank line (apparent off-by-one in input and validation output). TODO report.
 
 ## Julia performance issues/gotchas
-NB: the only place this matters in PALEO is for the model main loop.  Everything else is non-performance critical.
+NB: the only place this matters in PALEO is for the model main loop.  Everything else is non-performance critical. 
+The `PALEOboxes.TestUtils.bench_model` function provides a convenient way of benchmarking a model and identifying problem Reactions (where all Reactions in the registered PALEO packages should have zero allocations).
 - It is easy to write code which is 'type unstable', or generates memory allocations, which then gives low performance, see 'Performance tips' above.
 - Iterating over tuples: really need a `foreach` that is optimised eg <https://github.com/JuliaLang/julia/issues/31869>, <https://discourse.julialang.org/t/manually-unroll-operations-with-objects-of-tuple/11604>. PALEO provides `PALEOboxes.foreach_longtuple`.
 - @views for sparse matrices reverts to slow (dense) pathways (<https://stackoverflow.com/questions/58699267/julia-view-of-sparse-matrix>, <https://github.com/JuliaLang/julia/issues/21796>) (update - much improved in Julia 1.6 according to updates to these posts)

docs/src/HOWTOPython.md

@@ -1,49 +1,7 @@
 # Configuring for Julia - python interoperability
 
-Julia has near-seamless interoperability with Python, provided by the [PyCall.jl](https://github.com/JuliaPy/PyCall.jl) and [Conda.jl](https://github.com/JuliaPy/Conda.jl) packages in the [JuliaPy](https://github.com/JuliaPy) github organisation.
+Julia interoperability with Python is provided by the [PythonCall.jl](https://github.com/JuliaPy/PythonCall.jl) package in the [JuliaPy](https://github.com/JuliaPy) github organisation. This is now recommended over the earlier [PyCall.jl](https://github.com/JuliaPy/PyCall.jl) package.
 
-However configuration of Python and Julia inevitably introduces dependencies.  There are two overall strategies:
-1. allow Julia to install and maintain a private Python installion (the default)
-2. configure Julia and Python for a shared Python installation
+See <https://juliapy.github.io/PythonCall.jl/stable/pythoncall/#pythoncall-config> for configuration options to either use an existing python
+install from Julia, or to let Julia install it's own copy of python.
 
-## 1. Private Python installation for Julia
-This is simplest for cases where you just want to use a few python packages from Julia (eg IJulia for Jupyter notebooks).
-
-    julia> ENV["PYTHON"]="" 
-    julia> Pkg.add("PyCall")  # will build automatically
-
-Rebuild PyCall after installation to use private python installation:
-
-    julia> ENV["PYTHON"]="" 
-    julia> Pkg.build("PyCall")  # will rebuild to use private Python install, and install Matplotlib next time PyPlot is imported.
-
-(Re)build Julia packages that depend on python:
-
-    julia> ENV["JUPYTER"]="";
-    julia> Pkg.build("IJulia")  # force IJulia to use its own Conda-based Jupyter version
-
-
-## 2. Use an external python installation
-As of 2021-12-06, the simplest way to do this is to use [miniforge](https://github.com/conda-forge/miniforge) to manage the python installation.
-
-(Re)build [Conda.jl](https://github.com/JuliaPy/Conda.jl) to use the pre-existing Conda installation: 
-
-    julia> ENV["CONDA_JL_HOME"] = "/home/sd336/miniforge3/envs/conda_jl38"  # path from unix> conda info --envs
-    pkg> build Conda
-
-(Re)build [PyCall.jl](https://github.com/JuliaPy/PyCall.jl)
-
-    julia> ENV["PYTHON"] = "/home/sd336/miniforge3/envs/conda_jl38/bin/python"  # may be redundant (picks up location from Conda.jl ?)
-    pkg> build PyCall
-
-Restart Julia
-
-    julia> PyCall.libpython  # check we have picked up the new libpython etc
-    "/home/sd336/miniforge3/envs/conda_jl38/lib/libpython3.8.so.1.0"
-
-(Re)build [IJulia.jl](https://github.com/JuliaLang/IJulia.jl):
-
-    julia> ENV["JUPYTER"] = "/home/sd336/miniforge3/envs/conda_jl38/bin/jupyter" # path from unix> which jupyter
-    "/home/sd336/miniforge3/envs/conda_jl38/bin/jupyter"
-
-    pkg> build IJulia