Link check (MakieOrg#3451)

* check for invalid links * fix wrong links * exclude modules from api page * ignore specific missing links * couple more link fixes * remove comments again
t-bltg · Dec 6, 2023 · 53fb35d · 53fb35d
1 parent 838fe6a
commit 53fb35d
Show file tree

Hide file tree

Showing 10 changed files with 85 additions and 29 deletions.
diff --git a/docs/buildutils/relative_links.jl b/docs/buildutils/relative_links.jl
@@ -44,13 +44,39 @@ Replaces all absolute links in all html files in the __site folder with
 relative links.
 """
 function make_links_relative()
+ invalid_relative_links = Dict{String,Pair{String,String}}()
+
+ function check_local_link!(invalid_relative_links, file_location, link)
+ link_without_id = replace(link, r"#[a-zA-Z0-9!_\-\(\)]*$" => "")
+ absolute_link = if startswith(link, "/")
+ replace(link_without_id, r"^/+" => "")
+ else
+ normpath(joinpath(file_location, link_without_id))
+ end
+ _, ext = splitext(absolute_link)
+ if !isempty(ext)
+ if !isfile(absolute_link)
+ push!(invalid_relative_links, absolute_link => (file_location => link))
+ end
+ else
+ if !isfile(joinpath(absolute_link, "index.html"))
+ push!(invalid_relative_links, absolute_link => (file_location => link))
+ end
+ end
+ end
+
+ function is_local_link(link)
+ !startswith(link, "data:") && !startswith(link, r"https?") && !startswith(link, "#")
+ end
+
  cd("__site") do
  for (root, _, files) in walkdir(".")
  path = join(splitpath(root)[2:end], "/")
 
  html_files = filter(endswith(".html"), files)
  for file in html_files
- s = read(joinpath(root, file), String)
+ file_location = joinpath(root, file)
+ s = read(file_location, String)
  s = replace(s, '\0' => "\\0")
 
  html = parsehtml(s)
@@ -59,15 +85,27 @@ function make_links_relative()
  if (e isa HTMLElement{:script} || e isa HTMLElement{:img} || e isa HTMLElement{:video}) &&
  haskey(e.attributes, "src")
  link = e.attributes["src"]
- e.attributes["src"] = make_relative(link, path)
+ if is_local_link(link)
+ relative_link = make_relative(link, path)
+ check_local_link!(invalid_relative_links, root, link)
+ e.attributes["src"] = relative_link
+ end
 
  elseif (e isa HTMLElement{:link} || e isa HTMLElement{:a}) && haskey(e.attributes, "href")
  link = e.attributes["href"]
- e.attributes["href"] = make_relative(link, path)
+ if is_local_link(link)
+ relative_link = make_relative(link, path)
+ check_local_link!(invalid_relative_links, root, link)
+ e.attributes["href"] = relative_link
+ end
 
  elseif e isa HTMLElement{:form} && haskey(e.attributes, "action")
  link = e.attributes["action"]
- e.attributes["action"] = make_relative(link, path)
+ if is_local_link(link)
+ relative_link = make_relative(link, path)
+ check_local_link!(invalid_relative_links, root, link)
+ e.attributes["action"] = relative_link
+ end
  end
  end
 
@@ -77,4 +115,21 @@ function make_links_relative()
  end
  end
  end
-end
+
+ # these two are generated only in deployment
+ delete!(invalid_relative_links, "siteinfo.js")
+ delete!(invalid_relative_links, "../versions.js")
+
+ for (key, value) in invalid_relative_links
+ if startswith(key, "api/@ref")
+ @warn "Ignoring an invalid `@ref` link on the API page, this should be fixed: $key $value"
+ delete!(invalid_relative_links, key)
+ end
+ end
+
+ if !isempty(invalid_relative_links)
+ error("Found invalid relative links: \n$(join(invalid_relative_links, "\n"))")
+ end
+
+ return
+end
diff --git a/docs/colormap_generation.jl b/docs/colormap_generation.jl
@@ -47,7 +47,7 @@ end
 
 function generate_colorschemes_table(ks)
  extra_dir = get(ENV, "CI", "false") == "true" ? "../" : ""
- html = "<head><link type=\"text/css\" rel=\"stylesheet\" href=\"$(extra_dir)../assets/tables.css\" /></head><body><table><tr class=\"headerrow\">"
+ html = "<table><tr class=\"headerrow\">"
  for header in ["NAME", "Categorical variant", "Continuous variant"]
  html *= "<th>$header</th>"
  end
@@ -68,7 +68,7 @@ function generate_colorschemes_table(ks)
  # html *= colors_svg(cp7, 35, h)
  html *= "</td></tr>"
  end
- html *= "</table></body>"
+ html *= "</table>"
  return html
 end
 

diff --git a/docs/explanations/backends.md b/docs/explanations/backends.md
@@ -7,10 +7,10 @@ There are four backends which concretely implement all abstract rendering capabi
 
 | Package | Description |
 | :------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
-| [`GLMakie.jl`](/documentation/backends/glmakie/) | GPU-powered, interactive 2D and 3D plotting in standalone `GLFW.jl` windows. |
-| [`CairoMakie.jl`](/documentation/backends/cairomakie/) | `Cairo.jl` based, non-interactive 2D (and some 3D) backend for publication-quality vector graphics. |
-| [`WGLMakie.jl`](/documentation/backends/wglmakie/) | WebGL-based interactive 2D and 3D plotting that runs within browsers. |
-| [`RPRMakie.jl`](/documentation/backends/rprmakie/) | An experimental ray tracing backend. |
+| [`GLMakie.jl`](/explanations/backends/glmakie/) | GPU-powered, interactive 2D and 3D plotting in standalone `GLFW.jl` windows. |
+| [`CairoMakie.jl`](/explanations/backends/cairomakie/) | `Cairo.jl` based, non-interactive 2D (and some 3D) backend for publication-quality vector graphics. |
+| [`WGLMakie.jl`](/explanations/backends/wglmakie/) | WebGL-based interactive 2D and 3D plotting that runs within browsers. |
+| [`RPRMakie.jl`](/explanations/backends/rprmakie/) | An experimental ray tracing backend. |
 
 ### Activating Backends
 

diff --git a/docs/explanations/backends/glmakie.md b/docs/explanations/backends/glmakie.md
@@ -86,7 +86,7 @@ You can find a demo on how to set that up in this [nextjournal article](https://
 
 GLMakie's CI has no GPU, so you can also look at [.github/workflows/glmakie.yaml](https:/MakieOrg/Makie.jl/blob/master/.github/workflows/glmakie.yaml) for a working setup.
 
-If none of these work for you, take a look at the other [backends](/documentation/backends/), which all work without a GPU.
+If none of these work for you, take a look at the other [backends](/explanations/backends/), which all work without a GPU.
 
 If you get an error pointing to [GLFW.jl](https:/JuliaGL/GLFW.jl), please look into the existing [GLFW issues](https:/JuliaGL/GLFW.jl/issues), and also google for those errors. This is then very likely something that needs fixing in the [glfw c library](https:/glfw/glfw) or in the GPU drivers.
 

diff --git a/docs/explanations/backends/wglmakie.md b/docs/explanations/backends/wglmakie.md
@@ -306,7 +306,7 @@ end
 ```
 Or also specify a proxy URL, if you have a more complex proxy setup.
 For more advanced setups consult the `?Page` docs and `JSServe.configure_server!`.
-In the [headless](/documentation/headless/index.html#wglmakie) documentation, you can also read more about setting up the JSServe server and port forwarding.
+In the [headless](/explanations/headless/index.html#wglmakie) documentation, you can also read more about setting up the JSServe server and port forwarding.
 
 ## Styling
 

diff --git a/docs/explanations/headless.md b/docs/explanations/headless.md
@@ -48,7 +48,7 @@ This procedure is used in the [GLMakie tests](https:/MakieOrg/Makie.
 
 For WGLMakie, you can setup a server with JSServe and serve the content from a remote server.
 This also works for creating interactive plots with Documenter.
-Check out the [docs](/documentation/backends/wglmakie) for more details about this.
+Check out the [docs](/explanations/backends/wglmakie) for more details about this.
 
 If you want to use WGLMakie in VS Code on a remote server, you will have to forward the port
 used by WGLMakie in order for the plot pane integration to work.

diff --git a/docs/index.md b/docs/index.md
@@ -69,9 +69,9 @@ set_theme!() # hide
 
 ## Installation and Import
 
-Add one or more of the Makie backend packages [`GLMakie.jl`](/documentation/backends/glmakie/) (OpenGL), [`CairoMakie.jl`](/documentation/backends/cairomakie/) (Cairo), or [`WGLMakie.jl`](/documentation/backends/wglmakie/) (WebGL), [`RPRMakie`](/documentation/backends/rprmakie/) (RadeonProRender) using Julia's inbuilt package manager. Each backend re-exports `Makie` so there's no need to install it separately.
+Add one or more of the Makie backend packages [`GLMakie.jl`](/explanations/backends/glmakie/) (OpenGL), [`CairoMakie.jl`](/explanations/backends/cairomakie/) (Cairo), or [`WGLMakie.jl`](/explanations/backends/wglmakie/) (WebGL), [`RPRMakie`](/explanations/backends/rprmakie/) (RadeonProRender) using Julia's inbuilt package manager. Each backend re-exports `Makie` so there's no need to install it separately.
 
-Makie is the core package, and the backends have no user facing functionality. They only render the final result. See the [Backends](@ref) page for more information!
+Makie is the core package, and the backends have no user facing functionality. They only render the final result. See the \myreflink{Backends} page for more information!
 
 ```julia
 ]add GLMakie
@@ -133,7 +133,7 @@ There are four backends, each of which has particular strengths. You can switch
 
 @@box-container
  @@box
- ~~~<a class="boxlink" href="/documentation/backends/glmakie/">~~~
+ ~~~<a class="boxlink" href="/explanations/backends/glmakie/">~~~
  @@title GLMakie.jl@@
  @@box-content
  @@description
@@ -147,7 +147,7 @@ There are four backends, each of which has particular strengths. You can switch
  @@
 
  @@box
- ~~~<a class="boxlink" href="/documentation/backends/cairomakie/">~~~
+ ~~~<a class="boxlink" href="/explanations/backends/cairomakie/">~~~
  @@title CairoMakie.jl @@
  @@box-content
  @@description
@@ -161,7 +161,7 @@ There are four backends, each of which has particular strengths. You can switch
  @@
 
  @@box
- ~~~<a class="boxlink" href="/documentation/backends/wglmakie/">~~~
+ ~~~<a class="boxlink" href="/explanations/backends/wglmakie/">~~~
  @@title WGLMakie.jl @@
  @@box-content
  @@description
@@ -174,7 +174,7 @@ There are four backends, each of which has particular strengths. You can switch
  ~~~</a>~~~
  @@
  @@box
- ~~~<a class="boxlink" href="documentation/backends/rprmakie/">~~~
+ ~~~<a class="boxlink" href="explanations/backends/rprmakie/">~~~
  @@title RPRMakie.jl @@
  @@box-content
  @@description

diff --git a/docs/reference/blocks/lscene.md b/docs/reference/blocks/lscene.md
@@ -9,7 +9,7 @@ You can plot into the `LScene` directly, though.
 
 You can pass keyword arguments to the underlying `Scene` object to the `scenekw` keyword.
 Currently, it can be necessary to pass a couple of attributes explicitly to make sure they are not inherited from the main scene.
-To see what parameters are applicable, have a look at the [scene docs](/documentation/scenes)
+To see what parameters are applicable, have a look at the [scene docs](/explanations/scenes)
 
 \begin{examplefigure}{}
 ```julia

diff --git a/docs/reference/scene/lighting.md b/docs/reference/scene/lighting.md
@@ -26,7 +26,7 @@ Currently the following material attributes are available:
  See the [RPRMakie page](https://docs.makie.org/stable/documentation/backends/rprmakie/) for examples.
 
 
-## Lighting alogrithm
+## Lighting algorithm
 
 Lights are controlled through the `lights` vector in a `scene` and by the `shading` attribute in a plot.
 Generally you will not need to set `shading` yourself, as it is derived based on the lights vector.
@@ -160,15 +160,15 @@ ps = [
  for theta in range(-20, 20, length = 21) for phi in range(60, 340, length=30)
 ]
 faces = [QuadFace(30j + i, 30j + mod1(i+1, 30), 30*(j+1) + mod1(i+1, 30), 30*(j+1) + i) for j in 0:19 for i in 1:29]
-m = GeometryBasics.Mesh(meta(ps, normals = ps), decompose(GLTriangleFace, faces))
+marker_mesh = GeometryBasics.Mesh(meta(ps, normals = ps), decompose(GLTriangleFace, faces))
 
 lights = [PointLight(RGBf(10, 4, 2), Point3f(0, 0, 0), 5)]
 
 fig = Figure(size = (600, 600), backgroundcolor = :black)
 ax = LScene(fig[1, 1], scenekw = (lights = lights,), show_axis = false)
 update_cam!(ax.scene, ax.scene.camera_controls, Rect3f(Point3f(-2), Vec3f(4)))
 meshscatter!(
- ax, [Point3f(0) for _ in 1:14], marker = m, markersize = 0.1:0.2:3.0,
+ ax, [Point3f(0) for _ in 1:14], marker = marker_mesh, markersize = 0.1:0.2:3.0,
  color = :white, backlight = 1, transparency = false)
 fig
 ```
@@ -249,8 +249,8 @@ scene = LScene(
 )
 
 # floor
-p = mesh!(scene, Rect3f(Point3f(-10, -10, 0.01), Vec3f(20, 20, 0.02)), color = :white)
-translate!(p, 0, 0, -5)
+msh = mesh!(scene, Rect3f(Point3f(-10, -10, 0.01), Vec3f(20, 20, 0.02)), color = :white)
+translate!(msh, 0, 0, -5)
 
 # Cat
 cat_mesh = FileIO.load(Makie.assetpath("cat.obj"))
@@ -263,8 +263,7 @@ scale!(p2, Vec3f(4))
 # Window/light source markers
 for l in lights
  if l isa RectLight
- m = to_mesh(l)
- mesh!(m, color = :white, backlight = 1)
+ mesh!(to_mesh(l), color = :white, backlight = 1)
  end
 end
 

diff --git a/docs/utils.jl b/docs/utils.jl
@@ -21,7 +21,9 @@ using Makie
 
 function html_docstring(fname)
  fname == :SpecApi && return ""
- doc = Base.doc(getfield(Makie, Symbol(fname)))
+ obj = getfield(Makie, Symbol(fname))
+ obj isa Module && return "" # modules usually don't have docstrings and have READMEs copied in otherwise, which is messy
+ doc = Base.doc(obj)
  body = Markdown.html(doc)
 
  # body = fd2html(replace(txt, raw"$" => raw"\$"), internal = true)