Refactor make.jl (#766)

* Update make.jl to allow to exclude tutorial rendering.
* Add changelog entry.
* Update docs/make.jl
* Fix news, bump version.
* disable integration test for now.

---------

Co-authored-by: Mateusz Baran <[email protected]>

NEWS.md

@@ -5,12 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.10.6] – 2024-10-25
+## [0.10.6] – 2024-11-06
 
 ### Added
 
 * Two new actions: `ComplexPlanarRotation`, `QuaternionRotation`.
 * New function `quaternion_rotation_matrix` for converting quaternions to rotation matrices.
+* `make.jl` script now has more command line arguments, for example `--exclude-tutorials` when you do not want to build the tutorials but still look at the docs. See `make.jl --help` for more information.
 
 ## [0.10.5] – 2024-10-24
 

Project.toml

@@ -1,7 +1,7 @@
 name = "Manifolds"
 uuid = "1cead3c2-87b3-11e9-0ccd-23c62b72b94e"
 authors = ["Seth Axen <[email protected]>", "Mateusz Baran <[email protected]>", "Ronny Bergmann <[email protected]>", "Antoine Levitt <[email protected]>"]
-version = "0.10.5"
+version = "0.10.6"
 
 [deps]
 Einsum = "b7d42ee7-0b51-5a75-98ca-779d3107e4c0"

docs/make.jl

@@ -2,6 +2,32 @@
 #
 #
 
+if "--help" ∈ ARGS
+    println(
+        """
+docs/make.jl
+
+Render the `Manifolds.jl` documentation with optional arguments
+
+Arguments
+* `--exclude-tutorials` - exclude the tutorials from the menu of Documenter,
+  this can be used if you do not have Quarto installed to still be able to render the docs
+  locally on this machine. This option should not be set on CI.
+* `--help`              - print this help and exit without rendering the documentation
+* `--prettyurls`        – toggle the prettyurls part to true (which is otherwise only true on CI)
+* `--quarto`            – run the Quarto notebooks from the `tutorials/` folder before generating the documentation
+  this has to be run locally at least once for the `tutorials/*.md` files to exist that are included in
+  the documentation (see `--exclude-tutorials`) for the alternative.
+  If they are generated once they are cached accordingly.
+  Then you can spare time in the rendering by not passing this argument.
+  If quarto is not run, some tutorials are generated as empty files, since they
+  are referenced from within the documentation.
+  This is currently `getstarted.md`.
+""",
+    )
+    exit(0)
+end
+
 #
 # (a) if docs is not the current active environment, switch to it
 # (from https://github.com/JuliaIO/HDF5.jl/pull/1020/) 
@@ -11,26 +37,38 @@ if Base.active_project() != joinpath(@__DIR__, "Project.toml")
     Pkg.develop(PackageSpec(; path=(@__DIR__) * "/../"))
     Pkg.resolve()
     Pkg.instantiate()
-    if "--quarto" ∈ ARGS
-        Pkg.build("IJulia") # to activate the right kernel
-    end
 end
 
-# (b) Did someone say render? Then we render!
+# (b) Did someone say render?
 if "--quarto" ∈ ARGS
     using CondaPkg
     CondaPkg.withenv() do
         @info "Rendering Quarto"
         tutorials_folder = (@__DIR__) * "/../tutorials"
         # instantiate the tutorials environment if necessary
         Pkg.activate(tutorials_folder)
+        # For a breaking release -> also set the tutorials folder to the most recent version
         Pkg.develop(PackageSpec(; path=(@__DIR__) * "/../"))
         Pkg.resolve()
         Pkg.instantiate()
+        Pkg.build("IJulia") # build `IJulia` to the right version.
         Pkg.activate(@__DIR__) # but return to the docs one before
         run(`quarto render $(tutorials_folder)`)
         return nothing
     end
+else # fallback to at least create empty files for the start tutorial since that is linked
+    touch(joinpath(@__DIR__, "src/tutorials/getstarted.md"))
+end
+
+tutorials_in_menu = true
+if "--exclude-tutorials" ∈ ARGS
+    @warn """
+    You are excluding the tutorials from the Menu,
+    which might be done if you can not render them locally.
+
+    Remember that this should never be done on CI for the full documentation.
+    """
+    tutorials_in_menu = false
 end
 
 # (c) load necessary packages for the docs
@@ -65,7 +103,18 @@ for fname in ["CONTRIBUTING.md", "NEWS.md"]
     end
 end
 
-# (e) ...finally! make docs
+# (e) build the tutorials menu
+tutorials_menu =
+    "How to..." => [
+        "🚀 Get Started with `Manifolds.jl`" => "tutorials/getstarted.md",
+        "work in charts" => "tutorials/working-in-charts.md",
+        "perform Hand gesture analysis" => "tutorials/hand-gestures.md",
+        "integrate on manifolds and handle probability densities" => "tutorials/integration.md",
+        "explore curvature without coordinates" => "tutorials/exploring-curvature.md",
+        "work with groups" => "tutorials/groups.md",
+    ]
+# (f) final step: render the docs
+
 bib = CitationBibliography(joinpath(@__DIR__, "src", "references.bib"); style=:alpha)
 links = InterLinks(
     "ManifoldsBase" => ("https://juliamanifolds.github.io/ManifoldsBase.jl/stable/"),
@@ -93,26 +142,18 @@ if modules isa Vector{Union{Nothing,Module}}
     error("At least one module has not been properly loaded: ", modules)
 end
 makedocs(;
-    # for development, we disable prettyurls
     format=Documenter.HTML(
-        prettyurls=false,
+        prettyurls=(get(ENV, "CI", nothing) == "true") || ("--prettyurls" ∈ ARGS),
         assets=["assets/favicon.ico", "assets/citations.css"],
         size_threshold_warn=200 * 2^10, # raise slightly from 100 to 200 KiB
-        size_threshold=300 * 2^10,      # raise slightly 200 to to 300 KiB
+        size_threshold=300 * 2^10,      # raise slightly 200 to 300 KiB
     ),
     modules=modules,
     authors="Seth Axen, Mateusz Baran, Ronny Bergmann, and contributors.",
     sitename="Manifolds.jl",
     pages=[
         "Home" => "index.md",
-        "How to..." => [
-            "🚀 Get Started with `Manifolds.jl`" => "tutorials/getstarted.md",
-            "work in charts" => "tutorials/working-in-charts.md",
-            "perform Hand gesture analysis" => "tutorials/hand-gestures.md",
-            "integrate on manifolds and handle probability densities" => "tutorials/integration.md",
-            "explore curvature without coordinates" => "tutorials/exploring-curvature.md",
-            "work with groups" => "tutorials/groups.md",
-        ],
+        (tutorials_in_menu ? [tutorials_menu] : [])...,
         "Manifolds" => [
             "Basic manifolds" => [
                 "Centered matrices" => "manifolds/centeredmatrices.md",

docs/styles/config/vocabularies/Manifolds/accept.txt

@@ -1,4 +1,5 @@
 Grassmann
+[Jj]ulia
 Riemannian
 Stiefel
 [sS]ymplectic