ClimaOcean.jl/docs/make.jl at 60ff1b73f7beb4f64eaa4e2456b19da994426d27 · CliMA/ClimaOcean.jl · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
using
  ClimaOcean,
  CUDA,
  Documenter,
  DocumenterCitations,
  Literate

# temporary to enforce Oceananigans to use a specific branch
using Pkg
Pkg.add(PackageSpec(
    name = "Oceananigans",
    url = "https://github.com/CliMA/Oceananigans.jl",
    rev = "ss/omip-branch-2"
))

Pkg.add(PackageSpec(
    name = "ClimaSeaIce",
    url = "https://github.com/CliMA/ClimaSeaIce.jl",
    rev = "ss/omip-branch-2"
))
Pkg.resolve()
@show Pkg.status()

ENV["DATADEPS_ALWAYS_ACCEPT"] = "true"

bib_filepath = joinpath(dirname(@__FILE__), "climaocean.bib")
bib = CitationBibliography(bib_filepath, style=:authoryear)

#####
##### Generate examples
#####

const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
const OUTPUT_DIR   = joinpath(@__DIR__, "src/literated")

to_be_literated = [
    "single_column_os_papa_simulation.jl",
    "one_degree_simulation.jl",
    "near_global_ocean_simulation.jl"
]

for file in to_be_literated
    filepath = joinpath(EXAMPLES_DIR, file)
    withenv("JULIA_DEBUG" => "Literate") do
        Literate.markdown(filepath, OUTPUT_DIR; flavor = Literate.DocumenterFlavor(), execute = true)
    end
    GC.gc()
    CUDA.reclaim()
end

#####
##### Build and deploy docs
#####

format = Documenter.HTML(collapselevel = 2,
                         size_threshold = nothing,
                         canonical = "https://clima.github.io/ClimaOceanDocumentation/dev/")

pages = [
    "Home" => "index.md",

    "Examples" => [
        "Single-column ocean simulation" => "literated/single_column_os_papa_simulation.md",
        "One-degree ocean--sea ice simulation" => "literated/one_degree_simulation.md",
        "Near-global ocean simulation" => "literated/near_global_ocean_simulation.md",
        ],

    "Vertical grids" => "vertical_grids.md",

    "Interface fluxes" => "interface_fluxes.md",

    "Library" => [
        "Contents"       => "library/outline.md",
        "Public"         => "library/public.md",
        "Private"        => "library/internals.md",
        "Function index" => "library/function_index.md",
        ],
    "References" => "references.md",
]

makedocs(sitename = "ClimaOcean.jl";
         format,
         pages,
         plugins = [bib],
         modules = [ClimaOcean],
         doctest = true,
         clean = true,
         warnonly = [:cross_references, :missing_docs],
         checkdocs = :exports)

@info "Clean up temporary .jld2 and .nc output created by doctests or literated examples..."

"""
    recursive_find(directory, pattern)

Return list of filepaths within `directory` that contains the `pattern::Regex`.
"""
recursive_find(directory, pattern) =
    mapreduce(vcat, walkdir(directory)) do (root, dirs, files)
        joinpath.(root, filter(contains(pattern), files))
    end

files = []
for pattern in [r"\.jld2", r"\.nc"]
    global files = vcat(files, recursive_find(@__DIR__, pattern))
end

for file in files
    rm(file)
end

ci_build = get(ENV, "CI", nothing) == "true"

if ci_build
    deploydocs(repo = "github.com/CliMA/ClimaOceanDocumentation.git",
               deploy_config = Documenter.Buildkite(),
               versions = ["stable" => "v^", "dev" => "dev", "v#.#.#"],
               forcepush = true,
               devbranch = "main",
               push_preview = true)
end