add docs

Author: Datseris

.github/workflows/doccleanup.yml

@@ -0,0 +1,28 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - name: Delete preview and history
+        run: |
+            git config user.name "Documenter.jl"
+            git config user.email "documenter@juliadocs.github.io"
+            git rm -rf "previews/PR$PRNUM"
+            git commit -m "delete preview"
+            git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+        env:
+            PRNUM: ${{ github.event.number }}
+
+      - name: Push changes
+        run: |
+            git push --force origin gh-pages-new:gh-pages

.github/workflows/documentation.yml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.gitignore

@@ -4,3 +4,5 @@
 docs/build
 deps/build.log
 Manifest.toml
+*.scss
+*.css

docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
+PredefinedDynamicalSystems = "31e2f376-db9e-427a-b76e-a14f56347a14"

docs/make.jl

@@ -0,0 +1,56 @@
+cd(@__DIR__)
+CI = get(ENV, "CI", nothing) == "true" || get(ENV, "GITHUB_TOKEN", nothing) !== nothing
+using PredefinedDynamicalSystems # comes from global environment in CI
+using Documenter
+using DocumenterTools: Themes
+ENV["JULIA_DEBUG"] = "Documenter"
+
+# %% JuliaDynamics theme
+# It includes themeing for the HTML build
+# and themeing for the Makie plotting
+
+using DocumenterTools: Themes
+for file in ("juliadynamics-lightdefs.scss", "juliadynamics-darkdefs.scss", "juliadynamics-style.scss")
+    filepath = joinpath(@__DIR__, file)
+    if !isfile(filepath)
+        download("https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/$file", joinpath(@__DIR__, file))
+    end
+end
+# create the themes
+for w in ("light", "dark")
+    header = read(joinpath(@__DIR__, "juliadynamics-style.scss"), String)
+    theme = read(joinpath(@__DIR__, "juliadynamics-$(w)defs.scss"), String)
+    write(joinpath(@__DIR__, "juliadynamics-$(w).scss"), header*"\n"*theme)
+end
+# compile the themes
+Themes.compile(joinpath(@__DIR__, "juliadynamics-light.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-light.css"))
+Themes.compile(joinpath(@__DIR__, "juliadynamics-dark.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-dark.css"))
+
+# %% Build docs
+ENV["JULIA_DEBUG"] = "Documenter"
+
+include("style.jl")
+
+makedocs(
+    modules = [PredefinedDynamicalSystems],
+    format = Documenter.HTML(
+        prettyurls = CI,
+        assets = [
+            asset("https://fonts.googleapis.com/css?family=Montserrat|Source+Code+Pro&display=swap", class=:css),
+        ],
+        collapselevel = 3,
+    ),
+    sitename = "PredefinedDynamicalSystems.jl",
+    authors = "George Datseris",
+    pages = ["index.md"],
+    doctest = false,
+    draft = false,
+)
+
+if CI
+    deploydocs(
+        repo = "github.com/JuliaDynamics/PredefinedDynamicalSystems.jl.git",
+        target = "build",
+        push_preview = true
+    )
+end

docs/src/index.md

@@ -0,0 +1,13 @@
+# PredefinedDynamicalSystems.jl
+
+```@docs
+PredefinedDynamicalSystems
+```
+
+---
+
+All currently implemented predefined systems are listed below:
+```@autodocs
+Modules = [PredefinedDynamicalSystems]
+Order   = [:function]
+```

docs/style.jl

@@ -0,0 +1,39 @@
+# %% Color theme definitions
+struct CyclicContainer <: AbstractVector{String}
+    c::Vector{String}
+    n::Int
+end
+CyclicContainer(c) = CyclicContainer(c, 0)
+
+Base.length(c::CyclicContainer) = length(c.c)
+Base.size(c::CyclicContainer) = size(c.c)
+Base.iterate(c::CyclicContainer, state=1) = Base.iterate(c.c, state)
+Base.getindex(c::CyclicContainer, i) = c.c[(i-1)%length(c.c) + 1]
+Base.getindex(c::CyclicContainer, i::AbstractArray) = c.c[i]
+function Base.getindex(c::CyclicContainer)
+    c.n += 1
+    c[c.n]
+end
+Base.iterate(c::CyclicContainer, i = 1) = iterate(c.c, i)
+
+COLORSCHEME = [
+    "#6D44D0",
+    "#2CB3BF",
+    "#1B1B1B",
+    "#DA5210",
+    "#03502A",
+    "#866373",
+]
+
+COLORS = CyclicContainer(COLORSCHEME)
+LINESTYLES = CyclicContainer(["-", ":", "--", "-."])
+
+# %% Makie styling
+# other styling elements for Makie
+set_theme!(;
+    palette = (color = COLORSCHEME,),
+    fontsize = 22,
+    figure_padding = 4,
+    resolution = (1000, 500),
+    linewidth = 3.0,
+)

src/PredefinedDynamicalSystems.jl

@@ -4,8 +4,10 @@ The alias `Systems` is exported by `DynamicalSystems`.
 
 This module is provided purely as a convenience.
 Nothing here is tested, nor guaranteed to be stable in future versions.
+It is not recommended to use this module for anything else besides
+on-the-spot demonstrative examples.
 
-Predefined systems exist functions that
+Predefined systems exist as functions that
 return a `DynamicalSystem` instance. They are accessed like:
 ```julia
 ds = PredefinedDynamicalSystems.lorenz(u0; ρ = 32.0)