Skip to content

Commit 1ee8705

Browse files
tpoisottpoisot
authored
Merge 8d32dce into 074d436 
2 parents 074d436 + 8d32dce commit 1ee8705

File tree

8 files changed

+87
-75
lines changed

8 files changed

+87
-75
lines changed

‎docs/Project.toml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,6 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
77
DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
88
DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
99
Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
10-
FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
11-
GDAL = "add2ef01-049f-52c4-9ee2-e494f65e021a"
12-
GeoJSON = "61d90e0f-e114-555e-ac52-39dfb47a3ef9"
1310
InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
1411
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
1512
Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
@@ -21,4 +18,7 @@ SpatialBoundaries = "8d2ba62a-3d23-4a2b-b692-6b63e9267be2"
2118
StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
2219

2320
[compat]
24-
DocumenterVitepress = "0.1"
21+
Documenter = "1.13"
22+
DocumenterCitations = "1.4"
23+
DocumenterVitepress = "0.2"
24+
Literate = "2.20"

‎docs/make.jl‎

Lines changed: 14 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -3,79 +3,30 @@ sdt_path = dirname(dirname(Base.current_project()))
33
push!(LOAD_PATH, sdt_path)
44
using SpeciesDistributionToolkit
55

6-
# Load the rest of the build environment
6+
# These packages are required to build the documentation website
77
using Documenter
8-
using DocumenterVitepress
98
using DocumenterCitations
10-
using GeoJSON
9+
using DocumenterVitepress
10+
11+
# These packages are used to generate the cards (for datasets) and pages (for the manual)
1112
using Literate
1213
using Markdown
1314
using InteractiveUtils
1415
using Dates
1516
using PrettyTables
16-
import Downloads
17-
18-
# Download the bibliography from paperpile public URL
19-
const bibfile = joinpath(@__DIR__, "src", "references.bib")
20-
const paperpile_url = "https://paperpile.com/eb/nimbzsGosN"
21-
if isfile(bibfile)
22-
rm(bibfile)
23-
end
24-
Downloads.download(paperpile_url, bibfile)
25-
26-
# Cleanup the bibliography file to make DocumenterCitations happy despite their
27-
# refusal to acknowledge modern field names. The people will partu like it's
28-
# 1971 and they will like it.
29-
lines = readlines(bibfile)
30-
open(bibfile, "w") do bfile
31-
for line in lines
32-
if contains(line, "journaltitle")
33-
println(bfile, replace(line, "journaltitle" => "journal"))
34-
elseif contains(line, "date")
35-
yrmatch = match(r"{(\d{4})", line)
36-
if !isnothing(yrmatch)
37-
println(bfile, "year = {$(yrmatch[1])},")
38-
end
39-
println(bfile, line)
40-
else
41-
println(bfile, line)
42-
end
43-
end
44-
end
45-
# Look how they massacred my boy
46-
47-
bib = CitationBibliography(
48-
bibfile;
49-
style = :authoryear,
50-
)
51-
52-
# Generate a report card for each known dataset
53-
include("dataset_report.jl")
54-
include("polygon_report.jl")
55-
56-
# Additional functions to process the text when handled by Literate
57-
include("processing.jl")
5817

59-
# Changelogs
60-
include("changelogs.jl")
18+
# We will maintain the path to the root of the documentation here. This is
19+
# important to ensure that the script building the documentation works.
20+
const docpath = dirname(@__FILE__)
6121

62-
# Render the tutorials and how-to using Literate
63-
for folder in ["howto", "tutorials"]
64-
fpath = joinpath(@__DIR__, "src", folder)
65-
files_to_build = filter(endswith(".jl"), readdir(fpath; join = true))
66-
for docfile in files_to_build
67-
if ~isfile(replace(docfile, r".jl$" => ".md"))
68-
Literate.markdown(
69-
docfile, fpath;
70-
flavor = Literate.DocumenterFlavor(),
71-
config = Dict("credit" => false, "execute" => true),
72-
preprocess = pre!,
73-
postprocess = post!,
74-
)
75-
end
76-
end
77-
end
22+
# Steps required before the build
23+
include(joinpath("steps", "bibliography.jl")) # References for the doc
24+
include(joinpath("steps", "changelogs.jl")) # CHANGELOG files on the website
25+
include(joinpath("steps", "datasets.jl")) # Prepare the datasets vignettes
26+
include(joinpath("steps", "polygons.jl")) # Prepare the polygons vignettes
27+
include(joinpath("steps", "manual.jl")) # Compile the manual (this is the big one!)
7828

29+
# This MAKES the docs - this is required to succeed before we can deploy the docs
7930
makedocs(;
8031
sitename = "Species Distribution Toolkit",
8132
format = MarkdownVitepress(;

‎docs/src/howto/mask-polygons.jl‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,10 @@
22

33
using SpeciesDistributionToolkit
44
using CairoMakie
5-
import GeoJSON
65
CairoMakie.activate!(; type = "png", px_per_unit = 2) #hide
76

8-
# In this tutorial, we will clip a layer to a polygon (in GeoJSON format), then
9-
# use the same polygon to filter GBIF records.
7+
# In this tutorial, we will clip a layer to a polygon, then use the same polygon
8+
# to filter GBIF records.
109

1110
# ::: warning About coordinates
1211
#

‎docs/steps/bibliography.jl‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import Downloads
2+
3+
# Download the bibliography from paperpile public URL
4+
const bibfile = joinpath(docpath, "src", "references.bib")
5+
const paperpile_url = "https://paperpile.com/eb/nimbzsGosN"
6+
if isfile(bibfile)
7+
rm(bibfile)
8+
end
9+
10+
# This is the actual download of the bibliography. Note that we FORCE the
11+
# download at ever build, so that it is kept up to date (and it's also not
12+
# stored locally).
13+
Downloads.download(paperpile_url, bibfile)
14+
15+
# Cleanup the bibliography file to make DocumenterCitations happy despite their
16+
# refusal to acknowledge modern field names. The people will party like it's
17+
# 1971 and they will like it.
18+
lines = readlines(bibfile)
19+
open(bibfile, "w") do bfile
20+
for line in lines
21+
if contains(line, "journaltitle")
22+
println(bfile, replace(line, "journaltitle" => "journal"))
23+
elseif contains(line, "date")
24+
yrmatch = match(r"{(\d{4})", line)
25+
if !isnothing(yrmatch)
26+
println(bfile, "year = {$(yrmatch[1])},")
27+
end
28+
println(bfile, line)
29+
else
30+
println(bfile, line)
31+
end
32+
end
33+
end
34+
# Look how they massacred my boy
35+
36+
# This is what we return - the bibliography for the entire package documentation
37+
const bib = CitationBibliography(
38+
bibfile;
39+
style = :authoryear,
40+
)

‎docs/changelogs.jl‎ renamed to ‎docs/steps/changelogs.jl‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1-
chg_path = joinpath(dirname(dirname(@__FILE__)), "docs", "src", "reference", "changelog")
1+
# This file will create the changelogs for each packages. Specifically, it will
2+
# go through all the folders for component packages, then format the lines so
3+
# that any issue number is turned into a link to the repo. This happens
4+
# automatically during building, and requires no user input.
5+
6+
chg_path = joinpath(docpath, "src", "reference", "changelog")
27

38
if !ispath(chg_path)
49
mkpath(chg_path)
@@ -21,7 +26,7 @@ end
2126

2227
# SDT
2328
cp(
24-
joinpath(dirname(dirname(@__FILE__)), "CHANGELOG.md"),
29+
joinpath(dirname(docpath), "CHANGELOG.md"),
2530
joinpath(chg_path, "SpeciesDistributionToolkit.md");
2631
force = true,
2732
)
@@ -38,7 +43,7 @@ for pkg in [
3843
"PseudoAbsences",
3944
]
4045
cp(
41-
joinpath(dirname(dirname(@__FILE__)), pkg, "CHANGELOG.md"),
46+
joinpath(dirname(docpath), pkg, "CHANGELOG.md"),
4247
joinpath(chg_path, "$(pkg).md");
4348
force = true,
4449
)

‎docs/dataset_report.jl‎ renamed to ‎docs/steps/datasets.jl‎

File renamed without changes.

‎docs/processing.jl‎ renamed to ‎docs/steps/manual.jl‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,20 @@ function post_extract_table(content)
3535
content = replace(content, matcher => replacer)
3636
return content
3737
end
38+
39+
# Render the tutorials and how-to using Literate
40+
for folder in ["howto", "tutorials"]
41+
fpath = joinpath(@__DIR__, "src", folder)
42+
files_to_build = filter(endswith(".jl"), readdir(fpath; join = true))
43+
for docfile in files_to_build
44+
if ~isfile(replace(docfile, r".jl$" => ".md"))
45+
Literate.markdown(
46+
docfile, fpath;
47+
flavor = Literate.DocumenterFlavor(),
48+
config = Dict("credit" => false, "execute" => true),
49+
preprocess = pre!,
50+
postprocess = post!,
51+
)
52+
end
53+
end
54+
end

‎docs/polygon_report.jl‎ renamed to ‎docs/steps/polygons.jl‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ for P in subtypes(PolygonProvider)
5252
"w",
5353
) do io
5454
print(io, "# $(P) \n\n")
55-
print(io, "\n\n")
55+
return print(io, "\n\n")
5656
# print(io, "$(SimpleSDMDatasets.blurb(P))")
5757
# print(io, "\n\n")
5858
# print(io, "For more information about this provider: $(SimpleSDMDatasets.url(P))")
@@ -66,7 +66,7 @@ for P in subtypes(PolygonProvider)
6666
"a",
6767
) do io
6868
print(io, report(P, D))
69-
print(io, "\n\n")
69+
return print(io, "\n\n")
7070
end
7171
end
7272
end

0 commit comments

Comments
 (0)