Improve docs (#774)

* Improve docs.
* Remove artificial prefix emojis for Wikipedia.
* also remove the manual 🔗 prefix from earlier.
* A few improvements on the about page.
* finish extending docs.
* Forgot to add a link.
* Ah, relative links.
* fix a typo in a filename.
* Update docs/src/misc/about.md

---------

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

NEWS.md

@@ -5,6 +5,12 @@ 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.9] - unreleased
+
+### Changed
+
+* `about.md` now also lists contributors of manifolds and a very short history of the package.
+
 ## [0.10.8] – 2024-11-27
 
 ### Changed

docs/make.jl

@@ -11,25 +11,67 @@ 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.
+  This can be used if not all tutorials are rendered and you want to therefore exclude links
+  to these, especially the corresponding menu. This option should not be set on CI.
+  Locally this is also set if `--quarto` is not set and not all tutorials are rendered.
 * `--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.
+* `--prettyurls`        – toggle the pretty urls part to true, which is always set on CI
+* `--quarto`            – (re)run the Quarto notebooks from the `tutorials/` folder before
+  generating the documentation. 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
 
+run_quarto = "--quarto" in ARGS
+run_on_CI = (get(ENV, "CI", nothing) == "true")
+tutorials_in_menu = !("--exclude-tutorials" ∈ ARGS)
 #
-# (a) if docs is not the current active environment, switch to it
+#
+# (a) setup the tutorials menu – check whether all files exist
+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",
+    ]
+# Check whether all tutorials are rendered, issue a warning if not (and quarto if not set)
+all_tutorials_exist = true
+for (name, file) in tutorials_menu.second
+    fn = joinpath(@__DIR__, "src/", file)
+    if !isfile(fn) || filesize(fn) == 0 # nonexistent or empty file
+        global all_tutorials_exist = false
+        if !run_quarto
+            @warn "Tutorial $name does not exist at $fn."
+            if (!isfile(fn)) && (endswith(file, "getstarted.md"))
+                @warn "Generating empty file, since this tutorial is linked to from the documentation."
+                touch(fn)
+            end
+        end
+    end
+end
+if !all_tutorials_exist && !run_quarto && !run_on_CI
+    @warn """
+        Not all tutorials exist. Run `make.jl --quarto` to generate them. For this run they are excluded from the menu.
+    """
+    tutorials_in_menu = false
+end
+if !tutorials_in_menu
+    @warn """
+    You are either explicitly or implicitly excluding the tutorials from the documentation.
+    You will not be able to see their menu entries nor their rendered pages.
+    """
+    run_on_CI &&
+        (@error "On CI, the tutorials have to be either rendered with Quarto or be cached.")
+end
+#
+# (b) if docs is not the current active environment, switch to it
 # (from https://github.com/JuliaIO/HDF5.jl/pull/1020/) 
 if Base.active_project() != joinpath(@__DIR__, "Project.toml")
     using Pkg
@@ -39,8 +81,8 @@ if Base.active_project() != joinpath(@__DIR__, "Project.toml")
     Pkg.instantiate()
 end
 
-# (b) Did someone say render?
-if "--quarto" ∈ ARGS
+# (c) If quarto is set, or we are on CI, run quarto
+if run_quarto || run_on_CI
     using CondaPkg
     CondaPkg.withenv() do
         @info "Rendering Quarto"
@@ -56,22 +98,9 @@ if "--quarto" ∈ ARGS
         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
+# (d) load necessary packages for the docs
 using Plots, RecipesBase, Manifolds, ManifoldsBase, Documenter, PythonPlot
 using DocumenterCitations, DocumenterInterLinks
 # required for loading methods that handle differential equation solving
@@ -81,7 +110,7 @@ using NLsolve
 using Test, FiniteDifferences
 ENV["GKSwstype"] = "100"
 
-# (d) add CONTRIBUTING.md and NEWS.md to docs
+# (e) add CONTRIBUTING.md and NEWS.md to docs
 generated_path = joinpath(@__DIR__, "src", "misc")
 base_url = "https://github.com/JuliaManifolds/Manifolds.jl/blob/master/"
 isdir(generated_path) || mkdir(generated_path)
@@ -103,18 +132,7 @@ for fname in ["CONTRIBUTING.md", "NEWS.md"]
     end
 end
 
-# (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/"),
@@ -144,7 +162,7 @@ end
 makedocs(;
     format=Documenter.HTML(
         prettyurls=(get(ENV, "CI", nothing) == "true") || ("--prettyurls" ∈ ARGS),
-        assets=["assets/favicon.ico", "assets/citations.css"],
+        assets=["assets/favicon.ico", "assets/citations.css", "assets/link-icons.css"],
         size_threshold_warn=200 * 2^10, # raise slightly from 100 to 200 KiB
         size_threshold=300 * 2^10,      # raise slightly 200 to 300 KiB
     ),

docs/src/assets/link-icons.css

@@ -0,0 +1,41 @@
+a[href^="https://juliamanifolds.github.io/ManifoldsBase.jl/"]::before {
+    content: "";
+    background-image: url('logo-manifoldsbase.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+a[href^="https://manoptjl.org/"]::before {
+    content: "";
+    background-image: url('logo-manopt.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+a[href^="https://en.wikipedia.org/"]::before {
+    content: "";
+    background-image: url('wikipedia.png');
+    background-size: contain;
+    background-repeat: no-repeat;
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+@media (prefers-color-scheme: dark) {
+    a[href^="https://juliamanifolds.github.io/ManifoldsBase.jl/"]::before {
+        background-image: url('logo-manifoldsbase-dark.png');
+    }
+}

docs/src/misc/about.md

@@ -1,17 +1,36 @@
 # About `Manifolds.jl`
 
-## License
-
-[MIT License](https://github.com/JuliaManifolds/Manifolds.jl/blob/master/LICENSE)
+`Manifolds.jl` was started by [Seth Axen](https://github.com/sethaxen), [Mateusz Baran](https://github.com/mateuszbaran), [Ronny Bergmann](https://github.com/kellertuer), and [Antoine Levitt](https://github.com/antoine-levitt) in 2019, after a very fruitful discussion following the release of the first version of [`Manopt.jl`](https://manoptjl.org/). The goal of `Manifolds.jl` is to provide a library of manifolds in Julia. The manifolds are implemented using the [´ManifoldsBase.jl](https://github.com/JuliaManifolds/ManifoldsBase.jl/) interface.
 
-## Core Developers
+## Main developers
 
-- [Seth Axen](https://github.com/sethaxen)
 - [Mateusz Baran](https://github.com/mateuszbaran)
 - [Ronny Bergmann](https://github.com/kellertuer)
 
+## Former Main Developers
+
+- [Seth Axen](https://github.com/sethaxen)
+
 ## Contributors
+(in alphabetical order)
+
+- [Nick Dewaele](https://github.com/Nikdwal) contributed the [Tucker manifold](../manifolds/tucker.md)
+- [Renée Dornig](https://github.com/r-dornig) contributed the [centered  matrices](../manifolds/centeredmatrices.md) and the [essential manifold](../manifolds/essentialmanifold.md)
+- [David Hong](https://github.com/dahong67) contributed uniform distributions on the Stiefel and Grassmann manifolds.
+- [Johannes Voll Kolstø](https://github.com/johannvk) contributed the [symplectic manifold](../manifolds/symplectic.md), the [symplectic Stiefel manifold](../manifolds/symplecticstiefel.md)
+- [Manuel Weiß](https://github.com/manuelweisser) contributed [symmetric matrices](../manifolds/symmetric.md)
 
-See the [GitHub contributors page](https://github.com/JuliaManifolds/Manifolds.jl/graphs/contributors).
+as well as everyone else reporting, investigating, and fixing bugs or fixing typographical errors in the documentation, see the [GitHub contributors page](https://github.com/JuliaManifolds/Manifolds.jl/graphs/contributors).
+
+Of course all further [contributions](CONTRIBUTING.md) are always welcome!
+
+## Projects using `Manifolds.jl`
+
+- [Caesar.jl](https://juliarobotics.org/Caesar.jl/latest/concepts/using_manifolds/)
+- [ManoptExamples.jl](https://github.com/JuliaManifolds/ManoptExamples.jl) collecting examples of optimization problems on manifolds implemented using `Manifolds.jl` and [`Manopt.jl`](https://manoptjl.org).
+
+Do you use Manifolds.jl in you package? Let us know and open an [issue](https://github.com/JuliaManifolds/Manifolds.jl/issues/new/choose) or [pull request](https://github.com/JuliaManifolds/Manifolds.jl/compare) to add it to the list!
+
+## License
 
-[Contributions](CONTRIBUTING.md) are welcome!
+[MIT License](https://github.com/JuliaManifolds/Manifolds.jl/blob/master/LICENSE)

src/manifolds/FiberBundle.jl

@@ -57,7 +57,7 @@ end
 
 Fiber bundle on a [`AbstractManifold`](@extref `ManifoldsBase.AbstractManifold`)
 `M` of type [`FiberType`](@extref `ManifoldsBase.FiberType`).
-Examples include vector bundles, principal bundles or unit tangent bundles, see also [📖 Fiber Bundle](https://en.wikipedia.org/wiki/Fiber_bundle).
+Examples include vector bundles, principal bundles or unit tangent bundles, see also [Fiber Bundle](https://en.wikipedia.org/wiki/Fiber_bundle).
 
 # Fields
 * `manifold` – the [`AbstractManifold`](@extref `ManifoldsBase.AbstractManifold`)