Skip to content

Commit 2ab860b

Browse files
DatserisDatseris
authored
Update documentation build to documenter v1 (and fix it!) (#405)
* use JuliaDYnaics/doctheme updated * disable update message for now * add Cairomakie to doc deps * restore literate usage * add style files for reference * fix `Derived` usage and reference * remove documenter compat * fix the docbuild fail by not adding @pack in the docstrings
1 parent 59118d2 commit 2ab860b

11 files changed

+156
-81
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
Manifest.toml
2+
23
################################################################################
34
# DrWatson Project Structure #
45
################################################################################

‎docs/Project.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[deps]
2+
CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0" # not actually needed; but for doctheme
23
DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
34
Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
45
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
@@ -12,4 +13,4 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
1213
UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
1314

1415
[compat]
15-
Documenter = "0.24.6"
16+
Documenter = "1"

‎docs/build_docs_with_style.jl

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
CI = get(ENV, "CI", nothing) == "true" || get(ENV, "GITHUB_TOKEN", nothing) !== nothing
2+
3+
import Pkg
4+
Pkg.pkg"add Documenter@1"
5+
6+
# Load documenter
7+
using Documenter
8+
using DocumenterTools: Themes
9+
ENV["JULIA_DEBUG"] = "Documenter"
10+
11+
# For easier debugging when downloading from a specific branch.
12+
github_user = "JuliaDynamics"
13+
branch = "master"
14+
download_path = "https://raw.githubusercontent.com/$github_user/doctheme/$branch"
15+
16+
import Downloads
17+
for file in ("juliadynamics-lightdefs.scss", "juliadynamics-darkdefs.scss", "juliadynamics-style.scss")
18+
Downloads.download("$download_path/$file", joinpath(@__DIR__, file))
19+
end
20+
21+
# create the themes
22+
for w in ("light", "dark")
23+
header = read(joinpath(@__DIR__, "juliadynamics-style.scss"), String)
24+
theme = read(joinpath(@__DIR__, "juliadynamics-$(w)defs.scss"), String)
25+
write(joinpath(@__DIR__, "juliadynamics-$(w).scss"), header*"\n"*theme)
26+
end
27+
28+
# compile the themes
29+
Themes.compile(joinpath(@__DIR__, "juliadynamics-light.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-light.css"))
30+
Themes.compile(joinpath(@__DIR__, "juliadynamics-dark.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-dark.css"))
31+
32+
# Download and apply CairoMakie plotting style
33+
using CairoMakie
34+
Downloads.download("$download_path/style.jl", joinpath(@__DIR__, "style.jl"))
35+
include("style.jl")
36+
37+
function build_docs_with_style(pages, modules...; bib = nothing, authors = "George Datseris", draft = false, kwargs...)
38+
settings = (
39+
modules = [modules...],
40+
format = Documenter.HTML(
41+
prettyurls = CI,
42+
assets = [
43+
asset("https://fonts.googleapis.com/css?family=Montserrat|Source+Code+Pro&display=swap", class=:css),
44+
],
45+
collapselevel = 3,
46+
),
47+
sitename = "$(modules[1]).jl",
48+
authors,
49+
pages,
50+
draft,
51+
doctest = false,
52+
checkdocs = :exported,
53+
linkcheck_timeout = 2,
54+
# The following Documenter fails will NOT ERROR the docbuild!
55+
warnonly = [:doctest, :missing_docs],
56+
kwargs...
57+
)
58+
59+
if isnothing(bib)
60+
makedocs(; settings...)
61+
else
62+
makedocs(; plugins=[bib], settings...)
63+
end
64+
65+
if CI
66+
deploydocs(
67+
repo = "github.com/JuliaDynamics/$(modules[1]).jl.git",
68+
target = "build",
69+
push_preview = true
70+
)
71+
end
72+
73+
end

‎docs/make.jl

Lines changed: 21 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,29 @@
11
cd(@__DIR__)
2-
using Pkg
3-
CI = get(ENV, "CI", nothing) == "true" || get(ENV, "GITHUB_TOKEN", nothing) !== nothing
4-
CI && Pkg.activate(@__DIR__)
5-
CI && Pkg.instantiate()
62
using DrWatson
7-
using Documenter, DataFrames, Parameters, Dates, JLD2, UnPack
8-
using DocumenterTools: Themes
3+
using UnPack
94

10-
# %%
11-
# download the themes
12-
for file in ("juliadynamics-lightdefs.scss", "juliadynamics-darkdefs.scss", "juliadynamics-style.scss")
13-
download("https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/$file", joinpath(@__DIR__, file))
14-
end
15-
# create the themes
16-
for w in ("light", "dark")
17-
header = read(joinpath(@__DIR__, "juliadynamics-style.scss"), String)
18-
theme = read(joinpath(@__DIR__, "juliadynamics-$(w)defs.scss"), String)
19-
write(joinpath(@__DIR__, "juliadynamics-$(w).scss"), header*"\n"*theme)
20-
end
21-
# compile the themes
22-
Themes.compile(joinpath(@__DIR__, "juliadynamics-light.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-light.css"))
23-
Themes.compile(joinpath(@__DIR__, "juliadynamics-dark.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-dark.css"))
5+
# Convert workflow
6+
import Literate
247

25-
isdir(datadir()) && rm(datadir(); force = true, recursive = true)
8+
Literate.markdown(joinpath(@__DIR__, "src", "workflow.jl"), joinpath(@__DIR__, "src"); credit = false)
269

27-
using Literate
28-
Literate.markdown("src/workflow.jl", "src"; credit = false)
10+
pages = [
11+
"Introduction" => "index.md",
12+
"DrWatson Workflow Tutorial" => "workflow.md",
13+
"Project Setup" => "project.md",
14+
"Naming Simulations" => "name.md",
15+
"Saving Tools" => "save.md",
16+
"Running & Listing Simulations" => "run&list.md",
17+
"Real World Examples" => "real_world.md"
18+
]
2919

30-
makedocs(modules = [DrWatson, UnPack],
31-
sitename= "DrWatson",
32-
authors = "George Datseris and contributors.",
33-
doctest = false,
34-
format = Documenter.HTML(
35-
prettyurls = CI,
36-
assets = [
37-
"assets/logo.ico",
38-
asset("https://fonts.googleapis.com/css?family=Quicksand|Montserrat|Source+Code+Pro|Lora&display=swap", class=:css),
39-
],
40-
),
41-
pages = [
42-
"Introduction" => "index.md",
43-
"DrWatson Workflow Tutorial" => "workflow.md",
44-
"Project Setup" => "project.md",
45-
"Naming Simulations" => "name.md",
46-
"Saving Tools" => "save.md",
47-
"Running & Listing Simulations" => "run&list.md",
48-
"Real World Examples" => "real_world.md"
49-
],
20+
import Downloads
21+
Downloads.download(
22+
"https://raw.githubusercontent.com/JuliaDynamics/doctheme/master/build_docs_with_style.jl",
23+
joinpath(@__DIR__, "build_docs_with_style.jl")
5024
)
25+
include("build_docs_with_style.jl")
5126

52-
if CI
53-
deploydocs(
54-
repo = "github.com/JuliaDynamics/DrWatson.jl.git",
55-
target = "build",
56-
push_preview = true
57-
)
58-
end
27+
build_docs_with_style(pages, DrWatson, UnPack;
28+
expandfirst = ["index.md"], warnonly = true,
29+
)

‎docs/src/name.md

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,7 @@ tostringdict
2727
tosymboldict
2828
```
2929

30-
Notice that we also re-export the convenient `@pack!, @unpack` tools from [UnPack.jl](https://github.com/mauro3/UnPack.jl), because they play very well with [`@dict`](@ref) and similar functions. Be aware of the syntactic `,` difference: `d = @dict a b c` versus `@unpack a, b, c = d`.
31-
```@docs
32-
@unpack
33-
@pack!
34-
```
30+
DrWatson also re-exports `@pack!, @unpack` tools from [UnPack.jl](https://github.com/mauro3/UnPack.jl), because they play very well with [`@dict`](@ref) and similar functions. Be aware of the syntactic `,` difference: `d = @dict a b c` versus `@unpack a, b, c = d`.
3531

3632
## Customizing `savename`
3733
You can customize [`savename`](@ref) for your own Types. For example you could make it so that it only uses some specific keys instead of all of them, only specific types, or you could make it access data in a different way (maybe even loading files!). You can even make it have a custom `prefix`!

‎docs/src/real_world.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ path/to/project/data/sim/bk_N=50_T=10050_seed=1111_ΔT=1.jld2
9696
```
9797
and each file is a dictionary that has my data fields: `:U, :V, :simulation`, but also `:gitcommit, :script`. When I read this file I know exactly what was the source code that produced it (provided that I am not sloppy and commit code changes regularly :P).
9898

99-
## Customizing `savename`
99+
## [Customizing `savename`](@id customizing_savename)
100100
Here is a simple example for customizing [`savename`](@ref). We are using a common struct `Experiment` across different experiments with cats and mice.
101101

102102
We first define the relevant types.
@@ -355,7 +355,7 @@ using DrWatson
355355
general_args2 = Dict(
356356
"model" => "barkley",
357357
"noise" => [0.075, 0.050, 0.025],
358-
"noise2" => [1.0, ComputedParameter(["noise", "N"], (x,y) -> 2x + y)],
358+
"noise2" => [1.0, Derived(["noise", "N"], (x,y) -> 2x + y)],
359359
"noisy_training" => true,
360360
"N" => 100,
361361
)
@@ -617,7 +617,7 @@ julia> expensive_computation(5)
617617
```
618618

619619
## Taking project input-output automation to 11
620-
The point of this section is to show how far one can take the interplay between [`savename`](@ref) and [`produce_or_load`](@ref) to **automate project input-to-output and eliminate as many duplicate lines of code as possible**. Read [Customizing `savename`](@ref) first, as knowledge of that section is used here.
620+
The point of this section is to show how far one can take the interplay between [`savename`](@ref) and [`produce_or_load`](@ref) to **automate project input-to-output and eliminate as many duplicate lines of code as possible**. Read [Customizing `savename`](@ref customizing_savename) first, as knowledge of that section is used here.
621621

622622
The key ingredient is that [`produce_or_load`](@ref) was made to work well with [`savename`](@ref). You can use this to automate the input-to-output pipeline of your project by following these steps:
623623
1. Define a custom struct that represents the input configuration for an experiment or a simulation.

‎docs/src/run&list.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
It is very often the case that you want to run "batch simulations", i.e. just submit a bunch of different simulations, all using same algorithms and code but just different parameters. This scenario always requires the user to prepare a set of simulation parameter containers which are then passed into some kind of "main" function that starts the simulation.
55

66
To make the preparation part simpler we provide the following functionality:
7+
78
```@docs
89
dict_list
910
dict_list_count

‎docs/src/workflow.jl

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ initialize_project("DrWatsonExample"; authors="Datseris", force=true)
5050
# This project is now active by default so we can start adding packages
5151
# that we will be using in the project. We'll add the following for demonstrating
5252
using Pkg
53+
Pkg.develop("DrWatson") # hide
5354
Pkg.add(["Statistics", "JLD2"])
5455

5556
# ## 2. Write some scripts

‎docs/style.jl

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Color theme definitions
2+
struct CyclicContainer <: AbstractVector{String}
3+
c::Vector{String}
4+
n::Int
5+
end
6+
CyclicContainer(c) = CyclicContainer(c, 0)
7+
8+
Base.length(c::CyclicContainer) = length(c.c)
9+
Base.size(c::CyclicContainer) = size(c.c)
10+
Base.iterate(c::CyclicContainer, state=1) = iterate(c.c, state)
11+
Base.getindex(c::CyclicContainer, i) = c.c[(i-1)%length(c.c) + 1]
12+
Base.getindex(c::CyclicContainer, i::AbstractArray) = c.c[i]
13+
function Base.getindex(c::CyclicContainer)
14+
c.n += 1
15+
c[c.n]
16+
end
17+
Base.iterate(c::CyclicContainer, i = 1) = iterate(c.c, i)
18+
19+
COLORSCHEME = [
20+
"#7143E0",
21+
"#0A9A84",
22+
"#191E44",
23+
"#AF9327",
24+
"#701B80",
25+
"#2E6137",
26+
]
27+
28+
COLORS = CyclicContainer(COLORSCHEME)
29+
LINESTYLES = CyclicContainer(["-", ":", "--", "-."])
30+
31+
# other styling elements for Makie
32+
set_theme!(;
33+
palette = (color = COLORSCHEME,),
34+
fontsize = 22,
35+
figure_padding = 8,
36+
size = (800, 400),
37+
linewidth = 3.0,
38+
)

‎src/DrWatson.jl

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,8 @@ using Requires
5656
# Update messages
5757
using Scratch
5858
const env_var = "DRWATSON_UPDATE_MSG"
59-
const display_update = true
60-
const update_version = "2.12.0"
59+
const display_update = false
60+
const update_version = "-"
6161
const update_name = "update_v$update_version"
6262

6363
# Get scratch space for this package
@@ -85,13 +85,6 @@ function __init__()
8585
"""
8686
\nUpdate message: DrWatson v$update_version
8787
88-
- `produce_or_load` now allows using arbitrary functions when extracting a file
89-
name from the input configuration container. Effectively this means that you can
90-
use `Base.hash` instead of `savename`, allowing using `produce_or_load` with
91-
configuration containers that have too many parameters, or too complicated,
92-
to be uniquely mapped to a string via `savename`. A section "`produce_or_load`
93-
with hash codes" in Real World Examples highlights this possibility!
94-
9588
To disable future update messages see:
9689
https://juliadynamics.github.io/DrWatson.jl/stable/#Installing-and-Updating-1
9790
\n

‎src/dict_list.jl

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ To restrict some values in the dictionary so that they only appear in the
1515
resulting dictionaries, if a certain condition is met, the macro
1616
[`@onlyif`](@ref) can be used on those values.
1717
18-
To compute some parameters on creation of `dict_list` as a function
18+
To compute some parameters on creation of `dict_list` as a function
1919
of other specified parameters, use the type [`Derived`](@ref).
2020
2121
Use the function [`dict_list_count`](@ref) to get the number of
@@ -301,9 +301,11 @@ julia> dict_list(d) # only in case `:a` is `1` the dictionary will get key `:c`
301301

302302
"""
303303
Derived(parameters::Vector{Union{String,Symbol}}, function::Function)
304-
Wrap the name(s) of a parameter(s) and a function. After the
305-
possible parameter combinations are created, [`dict_list`](@ref) will replace instances of
306-
Derived by the result of the function func, evaluated with the value of
304+
Derived(parameter::Union{String,Symbol}, function::Function)
305+
306+
Wrap the name(s) of a parameter(s) and a function. After the
307+
possible parameter combinations are created, [`dict_list`](@ref) will replace instances of
308+
Derived by the result of the function func, evaluated with the value of
307309
the parameter(s).
308310
309311
## Examples
@@ -324,7 +326,7 @@ julia> dict_list(p)
324326
Dict(:α => 1, :solver => "SolverB", :β => 1)
325327
Dict(:α => 2, :solver => "SolverB", :β => 4)
326328
```
327-
A vector of parameter names can also be passed when the accompanying function
329+
A vector of parameter names can also be passed when the accompanying function
328330
uses multiple arguments:
329331
```julia
330332
julia> p2 = Dict(:α => [1, 2],
@@ -355,26 +357,24 @@ struct Derived{T}
355357
func::Function
356358
end
357359

358-
"""
359-
Derived(independentP :: Union{String,Symbol}, func::Function)
360-
Constructs a Derived from a single independent parameter.
361-
"""
362-
function Derived(independentP::Union{String,Symbol}, func::Function)
360+
# convenience dispatch
361+
function Derived(independentP::Union{String,Symbol}, func::Function)
363362
return Derived([independentP], func)
364363
end
365364

366365

367366
"""
368367
produce_computed_parameter(dicts)
368+
369369
Receive an array of parameter dictionaries, and for each one, evaluate
370-
the computed parameters after the possible combination of
370+
the computed parameters after the possible combination of
371371
parameters has been created.
372372
"""
373373
function produce_derived_parameters(dicts)
374374
for dict in dicts
375375
replace!(dict) do (k,v)
376-
if isa(v,Derived)
377-
k => v.func((dict[param] for param in v.independentParam)...)
376+
if isa(v,Derived)
377+
k => v.func((dict[param] for param in v.independentParam)...)
378378
else
379379
return k => v
380380
end

0 commit comments

Comments
 (0)