Update DocumenterVitepress (v0.2 changes)

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,79 +3,33 @@ 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,
-)
-
-# Generate a report card for each known dataset
-include("dataset_report.jl")
-include("polygon_report.jl")
 
-# Additional functions to process the text when handled by Literate
-include("processing.jl")
+# This is required as we refer to it in the documentation
+import GeoJSON
 
-# Changelogs
-include("changelogs.jl")
+# We will maintain the path to the root of the documentation here. This is
+# important to ensure that the script building the documentation works.
+const docpath = dirname(@__FILE__)
 
-# Render the tutorials and how-to using Literate
-for folder in ["howto", "tutorials"]
-    fpath = joinpath(@__DIR__, "src", folder)
-    files_to_build = filter(endswith(".jl"), readdir(fpath; join = true))
-    for docfile in files_to_build
-        if ~isfile(replace(docfile, r".jl$" => ".md"))
-            Literate.markdown(
-                docfile, fpath;
-                flavor = Literate.DocumenterFlavor(),
-                config = Dict("credit" => false, "execute" => true),
-                preprocess = pre!,
-                postprocess = post!,
-            )
-        end
-    end
-end
+# 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
+#include(joinpath("steps", "manual.jl")) # Compile the manual (this is the big one!)
 
+# This MAKES the docs - this is required to succeed before we can deploy the docs
 makedocs(;
     sitename = "Species Distribution Toolkit",
     format = MarkdownVitepress(;

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(docpath, "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.jl

@@ -1,4 +1,9 @@
-chg_path = joinpath(dirname(dirname(@__FILE__)), "docs", "src", "reference", "changelog")
+# 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(docpath, "src", "reference", "changelog")
 
 if !ispath(chg_path)
     mkpath(chg_path)
@@ -21,7 +26,7 @@ end
 
 # SDT
 cp(
-    joinpath(dirname(dirname(@__FILE__)), "CHANGELOG.md"),
+    joinpath(dirname(docpath), "CHANGELOG.md"),
     joinpath(chg_path, "SpeciesDistributionToolkit.md");
     force = true,
 )
@@ -38,7 +43,7 @@ for pkg in [
     "PseudoAbsences",  
 ]
     cp(
-        joinpath(dirname(dirname(@__FILE__)), pkg, "CHANGELOG.md"),
+        joinpath(dirname(docpath), pkg, "CHANGELOG.md"),
         joinpath(chg_path, "$(pkg).md");
         force = true,
     )

docs/dataset_report.jl → docs/steps/datasets.jl

@@ -124,7 +124,7 @@ function report(::Type{P}, ::Type{D}) where {P <: RasterProvider, D <: RasterDat
 end
 
 # Make sure the path is therethemes
-dataset_catalogue_path = joinpath("docs", "src", "datasets")
+dataset_catalogue_path = joinpath(docpath, "src", "datasets")
 if ~ispath(dataset_catalogue_path)
     mkpath(dataset_catalogue_path)
 end

docs/processing.jl → docs/steps/manual.jl

@@ -35,3 +35,20 @@ function post_extract_table(content)
     content = replace(content, matcher => replacer)
     return content
 end
+
+# Render the tutorials and how-to using Literate
+for folder in ["howto", "tutorials"]
+    fpath = joinpath(@__DIR__, "src", folder)
+    files_to_build = filter(endswith(".jl"), readdir(fpath; join = true))
+    for docfile in files_to_build
+        if ~isfile(replace(docfile, r".jl$" => ".md"))
+            Literate.markdown(
+                docfile, fpath;
+                flavor = Literate.DocumenterFlavor(),
+                config = Dict("credit" => false, "execute" => true),
+                preprocess = pre!,
+                postprocess = post!,
+            )
+        end
+    end
+end

docs/polygon_report.jl → docs/steps/polygons.jl

@@ -40,7 +40,7 @@ function report(::Type{P}, ::Type{D}) where {P <: PolygonProvider, D <: PolygonD
 end
 
 # Make sure the path is therethemes
-polygon_catalogue_path = joinpath("docs", "src", "polygons")
+polygon_catalogue_path = joinpath(docpath, "src", "polygons")
 if ~ispath(polygon_catalogue_path)
     mkpath(polygon_catalogue_path)
 end
@@ -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