Add Literate + LiveServer setup

.gitignore

@@ -1,6 +1,4 @@
 Manifest.toml
 docs/build/
 
-examples/markdowns/
-examples/notebooks/
-examples/scripts/
+docs/src/examples/generated/

docs/generate.jl

@@ -0,0 +1,31 @@
+# generate examples
+using Literate
+
+# Directory where the examples in Literate.jl format are
+EXAMPLEDIR = joinpath(@__DIR__, "src", "examples")
+# Directory where the examples will be generated
+GENERATEDDIR = joinpath(@__DIR__, "src", "examples", "generated")
+
+for example in readdir(EXAMPLEDIR)
+    ~endswith(example, ".jl") && continue
+    input = abspath(joinpath(EXAMPLEDIR, example))
+    #script = Literate.script(input, GENERATEDDIR)
+    #code = strip(read(script, String))
+    #mdpost(str) = replace(str, "@__CODE__" => code)
+    #Literate.markdown(input, GENERATEDDIR, postprocess = mdpost)
+    #Literate.notebook(input, GENERATEDDIR, execute = true) TODO try them notebooks
+    Literate.markdown(input, GENERATEDDIR)
+end
+
+# copy some figures to the build directory (no figures for me right now)
+# cp(joinpath(@__DIR__, "../examples/figures/heat_square.png"),
+#    joinpath(@__DIR__, "src/examples/generated/heat_equation.png"); force = true)
+# 
+# cp(joinpath(@__DIR__, "../examples/figures/coloring.png"),
+#    joinpath(@__DIR__, "src/examples/generated/coloring.png"); force = true)
+
+# remove any .vtu files in the generated dir (should not be deployed)
+# I don't even know what VTU files are... Leaving this here for now.
+cd(GENERATEDDIR) do
+    foreach(file -> endswith(file, ".vtu") && rm(file), readdir())
+end

docs/live.jl

@@ -0,0 +1,30 @@
+using LiveServer
+
+sw = LiveServer.SimpleWatcher()
+
+# source files to check for updates to avoid infinite loop
+EXAMPLEDIR = joinpath(@__DIR__, "src", "examples")
+EXAMPLES_jl = [f for f in readdir(EXAMPLEDIR) if endswith(f, ".jl")]
+SOURCES = [
+    joinpath(@__DIR__, "make.jl")
+    joinpath(@__DIR__, "src", "index.md")
+    joinpath(@__DIR__, "src", "prerequisites.md")
+    [joinpath(EXAMPLEDIR, example) for example in EXAMPLES_jl]
+]
+
+append!(sw.watchedfiles, LiveServer.WatchedFile.(SOURCES))
+
+function callback(x)
+    # only trigger for source files to avoid infinite loop
+    if x in SOURCES
+        include(joinpath(@__DIR__, "make.jl"))
+    end
+end
+
+callback(joinpath(@__DIR__, "make.jl")) # make sure files exist
+LiveServer.set_callback!(sw, callback)
+
+LiveServer.serve(sw; dir = joinpath(@__DIR__, "build"), verbose=true)
+
+
+

docs/make.jl

@@ -1,11 +1,33 @@
 using Documenter, AIBECS
 
+# Generate examples
+include("generate.jl")
+
+EXAMPLES_jl = [f for f in readdir(EXAMPLEDIR) if endswith(f, ".jl")]
+EXAMPLES_md = [replace(f, ".jl" => ".md") for f in EXAMPLES_jl]
+GENERATEDEXAMPLES = [joinpath("examples", "generated", f) for f in EXAMPLES_md]
+
 makedocs(
-    sitename="AIBECS Documentation",
+    sitename="AIBECS.jl",
+    doctest = false, # TODO guessing I should remove that when actually deploying?
     # options
-    modules = [AIBECS]
+    modules = [AIBECS],
+    # organisation
+    pages = Any[
+        "Home" => "index.md",
+        "Prerequisites" => "prerequisites.md",
+        "Examples" => GENERATEDEXAMPLES
+        ]
 )
 
+# make sure there are no *.vtu files left around from the build
+# Still do not know what these are
+cd(joinpath(@__DIR__, "build", "examples", "generated")) do
+    foreach(file -> endswith(file, ".vtu") && rm(file), readdir())
+end
+
+# Deploy
 deploydocs(
     repo = "github.com/briochemc/AIBECS.jl.git",
-)
+)
+

docs/src/index.md

@@ -1,28 +1,42 @@
-# AIBECS.jl Documentation
 
-(In construction)
+<img src="https://user-images.githubusercontent.com/4486578/57189839-c422db00-6f56-11e9-9e1d-26c8d9208702.png" alt="logo" title="AIBECS_logo" align="right" width="275"/>
 
-This package provides XXX.
+# AIBECS.jl
 
+(Work in Progress)
 
-## Usage
+## Introduction
 
-```@meta
-DocTestSetup = quote
-    using AIBECS
-    using LinearAlgebra, DiffEqBase
-end
-```
+AIBECS stands for the **Algebraic Implicit Biogeochemistry Element-Cycling System**.
+AIBECS may be pronounced like the cool [ibex](https://en.wikipedia.org/wiki/Ibex) (if you have a french accent).
+AIBECS is a new software written in [Julia](https://julialang.org) to easily create some marine biogeochmistry models in just a few commands.
 
-Load the OCIM 1.1 matrix and grid with 
+!!! note
+    AIBECS is developed primarily by Benoît Pasquier with the help of François Primeau and J. Keith Moore from the Department of Earth System Science at the University of California, Irvine, USA.
+    This software is in active development, so if you have any suggestions or feature requests, do not hesitate to start an issue directly on the [AIBECS GitHub repository](https://github.com/briochemc/AIBECS.jl)!
 
-```jldoctest usage
-wet3d, grd, T_OCIM = AIBECS.OCIM1.load()
-typeof(T_OCIM)
+AIBECS is not just a single model.
+It's a **system** that allows you to create a global steady-state biogeochmistry model with just a few simple commands.
+Basically, you just need to tell AIBECS
+- (i) which ocean circulation to use (from simple toy models of just a few boxes to more complicated global models of the circulation),
+- (ii) what elements you want to model/track and how each tracer gets converted into other tracers, and
+- (iii) chose some model parameters to start with.
+Once the model is set up, you can run simulations.
 
-# output
+AIBECS relies on many tools from linear algebra to run simulations and perform optimizations really fast.
+AIBECS-generated models are described by a state function, denoted $\boldsymbol{F}$, which defines how the concnetrations of elements in the ocean evolve with time.
+In mathematical terms, this translates to a system of nonlinear differential equations with the generic form 
 
-SparseMatrixCSC{Float64,Int64}
-```
+$$\frac{\partial \boldsymbol{x}}{\partial t} = \boldsymbol{F}(\boldsymbol{x}, \boldsymbol{p}),$$
 
+where $\boldsymbol{x}$ is the state of the model (i.e., the concentrations of the tracers), and $\boldsymbol{p}$ are model parameters.
+Here, we are interested in the equilibrium of the system (AKA the steady-state).
+That is when the time-derivative is $0$, so that
 
+$$\boldsymbol{F}(\boldsymbol{x}, \boldsymbol{p}) = 0,$$
+
+and $\boldsymbol{x}$ does not change with time.
+Instead of simulating the evolution of $\boldsymbol{x}$ with time and waiting for the system to reach equilibrium — like most biogeochemistry models do — AIBECS uses linear algebra techniques, like Newton's method in multiple dimensions, or Krylov spaces, to implicitly solve for the steady-state solution, hence the "algebraic" and "implicit" names.
+This makes AIBECS much faster than the competition!
+
+If you want to try AIBECS, head over to the prerequisites page to install the packages (this should take you a few minutes), and then open up one of the notebooks!

docs/src/prerequisites.md

@@ -0,0 +1,161 @@
+## Prerequisites
+
+This section provides a set of instructions and prerequisites to use AIBECS.
+
+### 1. Install Julia
+
+First things first, you must install [Julia](https://julialang.org). Click on the [Julia](https://julialang.org) link, look for the "download" buttons, and install the correct version for your OS.
+Once this is done, you should be able to start Julia by typing
+
+```bash
+julia
+```
+
+in the terminal.
+If not, find the Julia executable, and simply double click on it!
+This should open a terminal session, and display something like this:
+
+```julia
+               _
+   _       _ _(_)_     |  Documentation: https://docs.julialang.org
+  (_)     | (_) (_)    |
+   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
+  | | | | | | |/ _` |  |
+  | | |_| | | | (_| |  |  Version 1.1.1 (2019-05-16)
+ _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
+|__/                   |
+
+julia>
+```
+
+This is called the Julia REPL (for Read Eval Loop Print) and is used for interactive use of Julia.
+Great job, Julia is now running on your computer! Congratulations!
+
+If you want to learn more about Julia, you can read [the documentation](https://docs.julialang.org/en/v1/), there is a [Discourse forum](https://discourse.julialang.org/), and there is a [Slack channel](https://julialang.slack.com/messages) if you need help.
+But for now you should not need any of those: The notebook will just require you to press Shift + Enter a couple of times.
+
+### 2. Julia packages required for the notebooks
+
+In Julia, you can access the package manager by simply typing `]` in the REPL.
+Once you type `]`, the REPL changes to
+
+```julia
+(v1.1) pkg>
+```
+
+This means you're in the package-manager (or `pkg`) mode.
+
+Note that you can exit the `pkg` mode by pressing the `delete` key, and this will revert the Julia prompt to its original form:
+
+```julia
+julia>
+```
+
+The packages you should install are:
+
+- **AIBECS** (mandatory)
+
+    To create a global steady-state biogeochemistry model, we will be using the [AIBECS](https://github.com/briochemc/AIBECS.jl) package.
+    You install it, via
+
+    ```julia
+    add AIBECS
+    ```
+
+    in `pkg` mode, which should look like
+
+    ```julia
+    (v1.1) pkg> add AIBECS
+    ```
+
+    This should only take a few seconds.
+
+- If you want nice-looking maps, install **Cartopy**
+
+    In order to plot things, i.e., to look at the output of the beautiful work you will be doing with AIBECS, you will need a plotting package.
+    I suggest using Python's [Cartopy](https://scitools.org.uk/cartopy/docs/latest/) because, well, it looks pretty.
+    You can install it via the `Conda` package from within Julia.
+    Install it via `add Conda` in `pkg` mode.
+    You should see something like:
+
+    ```julia
+    (v1.1) pkg> add Conda
+    ```
+
+    Then back to the normal REPL mode (press `escape` to get the normal Julia REPL prompt), install cartopy within conda (within Julia) via
+
+    ```julia
+    julia> using Conda
+
+    julia> Conda.add("Cartopy")
+    ```
+
+
+    Then Install PyPlot:
+    ```julia
+    (v1.1) pkg> add PyPlot
+    ```
+
+    And PyCall:
+    ```julia
+    (v1.1) pkg> add PyCall
+    ```
+
+    This should only take a few seconds as well.
+
+    !!! note
+        You may want to install Cartopy differently, or even use a different plotting package.
+        This is merely a suggestion that has worked well for me.
+
+- If you want to run the notebooks, install **IJulia**
+
+    The [IJulia](https://github.com/JuliaLang/IJulia.jl) package allows you to launch JupyterLab from Julia.
+    To install it, in `pkg` mode, type `add IJulia` (and press return), and you should see something like:
+
+    ```julia
+    (v1.1) pkg> add IJulia
+    ```
+
+    This should only take a few seconds as well.
+
+    !!! note
+        You could install JupyterLab externally to Julia and use that instead.
+        The solution proposed here is to facilitate usage for those who do not already have or know how to install JupyterLab.
+
+    !!! note
+        You may need to build **CodecZlib** to run the notebooks.
+        If you see an error mentioning you should build it, then build it!
+        It's easy, just go in `pkg` mode and type `build CodecZlib`.
+        It should look like this:
+        ```julia
+        (v1.1) pkg> build CodecZlib
+        ```
+
+If you followed all these steps you should be able to use the notebooks!
+
+The final step is to start JupyterLab.
+First, make sure you are in the normal Julia REPL mode (i.e., press `delete` if you are in `pkg` mode.)
+Then, tell Julia that you want to "use" IJulia:
+
+```julia
+julia> using IJulia
+```
+
+!!! note
+    You can just copy paste the code above (including the `julia>` bits), and the REPL will know to not paste those automatically.
+    Everytime a package is used for the first time, Julia will precompile it (which can take a few seconds to minutes, depending on the package — don't worry, just let it finish).
+
+Finally, you can start JupyterLab from Julia by simply typing `jupyerlab()` in Julia.
+It should look like:
+
+```julia
+julia> jupyterlab()
+```
+
+!!! note
+    If Julia asks you if you want Conda to install JupyterLab, just say "yes" (i.e., type `y`).
+    After a couple seconds/minutes of downloads and installations, you should be all set up and a browser window should open with JupyterLab!
+
+Just navigate to the notebook of your choice with JupyterLab in your browser and double-click on the notebook!
+
+