Merge 9592294 into 074d436

Author: tpoisot

docs/Project.toml

@@ -7,9 +7,6 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
-FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
-GDAL = "add2ef01-049f-52c4-9ee2-e494f65e021a"
-GeoJSON = "61d90e0f-e114-555e-ac52-39dfb47a3ef9"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
@@ -21,4 +18,7 @@ SpatialBoundaries = "8d2ba62a-3d23-4a2b-b692-6b63e9267be2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 
 [compat]
-DocumenterVitepress = "0.1"
+Documenter = "1.13"
+DocumenterCitations = "1.4"
+DocumenterVitepress = "0.2"
+Literate = "2.20"

docs/make.jl

@@ -3,51 +3,23 @@ sdt_path = dirname(dirname(Base.current_project()))
 push!(LOAD_PATH, sdt_path)
 using SpeciesDistributionToolkit
 
-# Load the rest of the build environment
+# These packages are required to build the documentation website
 using Documenter
-using DocumenterVitepress
 using DocumenterCitations
-using GeoJSON
+using DocumenterVitepress
+
+# These packages are used to generate the cards (for datasets) and pages (for the manual)
 using Literate
 using Markdown
 using InteractiveUtils
 using Dates
 using PrettyTables
-import Downloads
 
-# Download the bibliography from paperpile public URL
-const bibfile = joinpath(@__DIR__, "src", "references.bib")
-const paperpile_url = "https://paperpile.com/eb/nimbzsGosN"
-if isfile(bibfile)
-    rm(bibfile)
-end
-Downloads.download(paperpile_url, bibfile)
-
-# Cleanup the bibliography file to make DocumenterCitations happy despite their
-# refusal to acknowledge modern field names. The people will partu like it's
-# 1971 and they will like it.
-lines = readlines(bibfile)
-open(bibfile, "w") do bfile
-    for line in lines
-        if contains(line, "journaltitle")
-            println(bfile, replace(line, "journaltitle" => "journal"))
-        elseif contains(line, "date")
-            yrmatch = match(r"{(\d{4})", line)
-            if !isnothing(yrmatch)
-                println(bfile, "year = {$(yrmatch[1])},")
-            end
-            println(bfile, line)
-        else
-            println(bfile, line)
-        end
-    end
-end
-# Look how they massacred my boy
-
-bib = CitationBibliography(
-    bibfile;
-    style = :authoryear,
-)
+# Steps required before the build
+include(joinpath("steps", "bibliography.jl")) # References for the doc
+include(joinpath("steps", "changelogs.jl")) # CHANGELOG files on the website
+include(joinpath("steps", "datasets.jl")) # Prepare the datasets vignettes
+include(joinpath("steps", "polygons.jl")) # Prepare the polygons vignettes
 
 # Generate a report card for each known dataset
 include("dataset_report.jl")
@@ -56,9 +28,6 @@ include("polygon_report.jl")
 # Additional functions to process the text when handled by Literate
 include("processing.jl")
 
-# Changelogs
-include("changelogs.jl")
-
 # Render the tutorials and how-to using Literate
 for folder in ["howto", "tutorials"]
     fpath = joinpath(@__DIR__, "src", folder)

docs/src/howto/mask-polygons.jl

@@ -2,11 +2,10 @@
 
 using SpeciesDistributionToolkit
 using CairoMakie
-import GeoJSON
 CairoMakie.activate!(; type = "png", px_per_unit = 2) #hide
 
-# In this tutorial, we will clip a layer to a polygon (in GeoJSON format), then
-# use the same polygon to filter GBIF records.
+# In this tutorial, we will clip a layer to a polygon, then use the same polygon
+# to filter GBIF records.
 
 # ::: warning About coordinates
 # 

docs/steps/bibliography.jl

@@ -0,0 +1,40 @@
+import Downloads
+
+# Download the bibliography from paperpile public URL
+const bibfile = joinpath(@__DIR__, "src", "references.bib")
+const paperpile_url = "https://paperpile.com/eb/nimbzsGosN"
+if isfile(bibfile)
+    rm(bibfile)
+end
+
+# This is the actual download of the bibliography. Note that we FORCE the
+# download at ever build, so that it is kept up to date (and it's also not
+# stored locally).
+Downloads.download(paperpile_url, bibfile)
+
+# Cleanup the bibliography file to make DocumenterCitations happy despite their
+# refusal to acknowledge modern field names. The people will party like it's
+# 1971 and they will like it.
+lines = readlines(bibfile)
+open(bibfile, "w") do bfile
+    for line in lines
+        if contains(line, "journaltitle")
+            println(bfile, replace(line, "journaltitle" => "journal"))
+        elseif contains(line, "date")
+            yrmatch = match(r"{(\d{4})", line)
+            if !isnothing(yrmatch)
+                println(bfile, "year = {$(yrmatch[1])},")
+            end
+            println(bfile, line)
+        else
+            println(bfile, line)
+        end
+    end
+end
+# Look how they massacred my boy
+
+# This is what we return - the bibliography for the entire package documentation
+const bib = CitationBibliography(
+    bibfile;
+    style = :authoryear,
+)

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

@@ -1,3 +1,8 @@
+# This file will create the changelogs for each packages. Specifically, it will
+# go through all the folders for component packages, then format the lines so
+# that any issue number is turned into a link to the repo. This happens
+# automatically during building, and requires no user input.
+
 chg_path = joinpath(dirname(dirname(@__FILE__)), "docs", "src", "reference", "changelog")
 
 if !ispath(chg_path)

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

@@ -52,7 +52,7 @@ for P in subtypes(PolygonProvider)
         "w",
     ) do io
         print(io, "# $(P) \n\n")
-        print(io, "\n\n")
+        return print(io, "\n\n")
         # print(io, "$(SimpleSDMDatasets.blurb(P))")
         # print(io, "\n\n")
         # print(io, "For more information about this provider: $(SimpleSDMDatasets.url(P))")
@@ -66,7 +66,7 @@ for P in subtypes(PolygonProvider)
                 "a",
             ) do io
                 print(io, report(P, D))
-                print(io, "\n\n")
+                return print(io, "\n\n")
             end
         end
     end