From 5b1072a2a2fb2e4be0e86329d17c27872d776b10 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Thu, 20 Feb 2025 10:48:57 -0500 Subject: [PATCH 01/14] Create an interface for column components other than MultiDocRef --- src/MultiDocumenter.jl | 43 +++++++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index 34efef2a..ff916aec 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -25,6 +25,23 @@ Base.@kwdef mutable struct SearchConfig lowfi = false end +""" + abstract type DropdownComponent + +The supertype for any component that can be put in a dropdown column and +rendered using `MultiDocumenter.render(::YourComponent, thispagepath, dir, prettyurls)`. + +All `DropdownComponent`s go in [`Column`](@ref)s, which go in [`MegaDropdownNav`](@ref). + +Any subtype of `DropdownComponent` must implement that `render` method. + +The main subtype is [`MultiDocRef`](@ref), which refers to external documentation +and adds it to the search index. However, there are others like [`ExternalLink`](@ref) +which is used to link to external sites without making them searchable, and +users can implement their own custom components. +""" +abstract type DropdownComponent end + """ struct MultiDocRef @@ -44,7 +61,7 @@ Represents one set of docs that will get an entry in the MultiDocumenter navigat * `fix_canonical_url`: this can be set to `false` to disable the canonical URL fixing for this `MultiDocRef` (see also `canonical_domain` for [`make`](@ref)). """ -struct MultiDocRef +struct MultiDocRef <: DropdownComponent upstream::String path::String name::Any @@ -66,12 +83,12 @@ end struct DropdownNav name::String - children::Vector{MultiDocRef} + children::Vector{DropdownComponent} end struct Column name::Any - children::Vector{MultiDocRef} + children::Vector{DropdownComponent} end struct MegaDropdownNav @@ -84,8 +101,8 @@ struct BrandImage imagepath::String end -function walk_outputs(f, root, docs::Vector{MultiDocRef}, dirs::Vector{String}) - for ref in docs +function walk_outputs(f, root, docs::Vector, dirs::Vector{String}) + for ref in filter(x -> x isa MultiDocRef, docs) p = joinpath(root, ref.path) for dir in dirs dirpath = joinpath(p, dir) @@ -143,7 +160,7 @@ Aggregates multiple Documenter.jl-based documentation pages `docs` into `outdir` """ function make( outdir, - docs::Vector; + docs::Vector{DropdownComponent}; assets_dir = nothing, brand_image::Union{Nothing,BrandImage} = nothing, custom_stylesheets = [], @@ -256,9 +273,9 @@ function make( end function flatten_multidocrefs(docs::Vector) - out = MultiDocRef[] + out = [] for doc in docs - if doc isa MultiDocRef + if doc isa DropdownComponent push!(out, doc) elseif doc isa MegaDropdownNav for col in doc.columns @@ -275,8 +292,8 @@ function flatten_multidocrefs(docs::Vector) out end -function maybe_clone(docs::Vector{MultiDocRef}) - for doc in docs +function maybe_clone(docs::Vector{<: DropdownComponent}) + for doc in filter(x -> x isa MultiDocRef, docs) if !isdir(doc.upstream) if isempty(doc.giturl) error( @@ -314,14 +331,14 @@ function maybe_clone(docs::Vector{MultiDocRef}) end function make_output_structure( - docs::Vector{MultiDocRef}, + docs::Vector{<: DropdownComponent}, prettyurls, hide_previews; canonical::Union{AbstractString,Nothing}, ) dir = mktempdir() - for doc in docs + for doc in Iterators.filter(x -> x isa MultiDocRef, docs) outpath = joinpath(dir, doc.path) mkpath(dirname(outpath)) @@ -355,7 +372,7 @@ end function make_global_nav( dir, - docs::Vector, + docs::Vector{<: DropdownComponent}, thispagepath, brand_image, search_engine, From 7acd3aef67ff94f222004cc09f1e98993a20d9d1 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Thu, 20 Feb 2025 10:57:26 -0500 Subject: [PATCH 02/14] Fix whitespace issues suggested by Semgrep Co-authored-by: semgrep-code-juliacomputing-new[bot] <177960334+semgrep-code-juliacomputing-new[bot]@users.noreply.github.com> --- src/MultiDocumenter.jl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index ff916aec..3e7302d5 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -35,9 +35,9 @@ All `DropdownComponent`s go in [`Column`](@ref)s, which go in [`MegaDropdownNav` Any subtype of `DropdownComponent` must implement that `render` method. -The main subtype is [`MultiDocRef`](@ref), which refers to external documentation -and adds it to the search index. However, there are others like [`ExternalLink`](@ref) -which is used to link to external sites without making them searchable, and +The main subtype is [`MultiDocRef`](@ref), which refers to external documentation +and adds it to the search index. However, there are others like [`ExternalLink`](@ref) +which is used to link to external sites without making them searchable, and users can implement their own custom components. """ abstract type DropdownComponent end From 4aeb4be6441dc8f109972c08cb75f0d0f8fae6bb Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Thu, 20 Feb 2025 11:20:34 -0500 Subject: [PATCH 03/14] Don't restrict types --- src/MultiDocumenter.jl | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index 3e7302d5..e341b24b 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -160,7 +160,7 @@ Aggregates multiple Documenter.jl-based documentation pages `docs` into `outdir` """ function make( outdir, - docs::Vector{DropdownComponent}; + docs::Vector; assets_dir = nothing, brand_image::Union{Nothing,BrandImage} = nothing, custom_stylesheets = [], @@ -292,7 +292,7 @@ function flatten_multidocrefs(docs::Vector) out end -function maybe_clone(docs::Vector{<: DropdownComponent}) +function maybe_clone(docs::Vector) for doc in filter(x -> x isa MultiDocRef, docs) if !isdir(doc.upstream) if isempty(doc.giturl) @@ -331,7 +331,7 @@ function maybe_clone(docs::Vector{<: DropdownComponent}) end function make_output_structure( - docs::Vector{<: DropdownComponent}, + docs::Vector, prettyurls, hide_previews; canonical::Union{AbstractString,Nothing}, @@ -372,7 +372,7 @@ end function make_global_nav( dir, - docs::Vector{<: DropdownComponent}, + docs::Vector, thispagepath, brand_image, search_engine, From 4d4fab3ad650a615db949169a9c9100e14328eda Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Thu, 20 Feb 2025 11:37:15 -0500 Subject: [PATCH 04/14] add a Link component to emphasize the renderer interface --- src/MultiDocumenter.jl | 8 ++++++++ src/renderers.jl | 6 ++++++ 2 files changed, 14 insertions(+) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index e341b24b..f2e30612 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -81,6 +81,14 @@ function MultiDocRef(; MultiDocRef(upstream, path, name, fix_canonical_url, giturl, branch) end + +struct Link <: MultiDocumenter.DropdownComponent + text::String + link::String +end + +Link(link::String) = Link(link, link) + struct DropdownNav name::String children::Vector{DropdownComponent} diff --git a/src/renderers.jl b/src/renderers.jl index 76d6cedf..876e34b7 100644 --- a/src/renderers.jl +++ b/src/renderers.jl @@ -36,6 +36,12 @@ function render(doc::MultiDocRef, dir, thispagepath, prettyurls) """ end +function render(c::Link, doc, thispage, prettyurls) + return @htl """ + $(c.text) + """ # TODO: add "external link" icon after, either chain or arrow exiting box. +end + function render(doc::DropdownNav, dir, thispagepath, prettyurls) return @htl """
From b22d26b6ce6f4e843ca95f2cf7bd16398f59c691 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Thu, 20 Feb 2025 11:37:36 -0500 Subject: [PATCH 05/14] Use that link in docs and tests --- docs/make.jl | 4 ++++ test/runtests.jl | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/make.jl b/docs/make.jl index df9a46d6..7249b4a0 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -87,6 +87,10 @@ docs = [ name = "JuliaInterpreter", giturl = "https://github.com/JuliaDebug/JuliaInterpreter.jl.git", ), + MultiDocumenter.Link( + "Lux", + "https://github.com/avik-pal/Lux.jl", + ), ], ), MultiDocumenter.Column( diff --git a/test/runtests.jl b/test/runtests.jl index cfdae536..d5e041e9 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -54,6 +54,10 @@ docs = [ name = "Lux", giturl = "https://github.com/avik-pal/Lux.jl", ), + MultiDocumenter.Link( + "JuliaHub", + "https://juliahub.com", + ), ], ), MultiDocumenter.Column( From a02cb96e1065ca920f6c5de3ea162fd114e9bb32 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Thu, 20 Feb 2025 11:46:20 -0500 Subject: [PATCH 06/14] code style changes --- src/MultiDocumenter.jl | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index f2e30612..607e8bf7 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -281,7 +281,7 @@ function make( end function flatten_multidocrefs(docs::Vector) - out = [] + out = DropdownComponent[] for doc in docs if doc isa DropdownComponent push!(out, doc) @@ -297,7 +297,7 @@ function flatten_multidocrefs(docs::Vector) end end end - out + return out end function maybe_clone(docs::Vector) @@ -336,6 +336,7 @@ function maybe_clone(docs::Vector) end end end + return nothing end function make_output_structure( From eb4edc2eb62f9aab5ff007a12b080ff4b082155c Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Fri, 21 Feb 2025 17:16:40 -0500 Subject: [PATCH 07/14] `flatten_multidocrefs` -> `flatten_dropdowncomponents` --- src/MultiDocumenter.jl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index 607e8bf7..23e9087e 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -224,10 +224,10 @@ function make( end site_root_url = string(canonical_domain, rstrip(rootpath, '/')) - maybe_clone(flatten_multidocrefs(docs)) + maybe_clone(flatten_dropdowncomponents(docs)) dir = make_output_structure( - flatten_multidocrefs(docs), + flatten_dropdowncomponents(docs), prettyurls, hide_previews; canonical = site_root_url, @@ -260,7 +260,7 @@ function make( if search_engine != false search_engine.engine.build_search_index( dir, - flatten_multidocrefs(docs), + flatten_dropdowncomponents(docs), search_engine, rootpath, ) @@ -280,7 +280,7 @@ function make( return outdir end -function flatten_multidocrefs(docs::Vector) +function flatten_dropdowncomponents(docs::Vector) out = DropdownComponent[] for doc in docs if doc isa DropdownComponent @@ -340,7 +340,7 @@ function maybe_clone(docs::Vector) end function make_output_structure( - docs::Vector, + docs::Vector{DropdownComponent}, prettyurls, hide_previews; canonical::Union{AbstractString,Nothing}, From 3a47640675361f4dc25b4eefe0048991ff393ee9 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Fri, 21 Feb 2025 17:16:48 -0500 Subject: [PATCH 08/14] Finish refactoring Link --- src/MultiDocumenter.jl | 6 +++++- src/renderers.jl | 8 ++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index 23e9087e..1fcfd5ac 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -36,7 +36,7 @@ All `DropdownComponent`s go in [`Column`](@ref)s, which go in [`MegaDropdownNav` Any subtype of `DropdownComponent` must implement that `render` method. The main subtype is [`MultiDocRef`](@ref), which refers to external documentation -and adds it to the search index. However, there are others like [`ExternalLink`](@ref) +and adds it to the search index. However, there are others like [`Link`](@ref) which is used to link to external sites without making them searchable, and users can implement their own custom components. """ @@ -81,7 +81,11 @@ function MultiDocRef(; MultiDocRef(upstream, path, name, fix_canonical_url, giturl, branch) end +""" + Link([text::String], link::String) <: DropdownComponent +Represents a link to an external site. +""" struct Link <: MultiDocumenter.DropdownComponent text::String link::String diff --git a/src/renderers.jl b/src/renderers.jl index 876e34b7..7aefd83e 100644 --- a/src/renderers.jl +++ b/src/renderers.jl @@ -37,9 +37,13 @@ function render(doc::MultiDocRef, dir, thispagepath, prettyurls) end function render(c::Link, doc, thispage, prettyurls) + # class nav-link nav-item makes the formatting correct + # _target="blank" opens the link in a new tab + # TODO: add "external link" icon after, either chain or arrow exiting box. + # TODO: allow internal links return @htl """ - $(c.text) - """ # TODO: add "external link" icon after, either chain or arrow exiting box. + $(c.text) + """ end function render(doc::DropdownNav, dir, thispagepath, prettyurls) From 0612758b69a90cec8491dca5867a0f21e31e87b3 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Fri, 21 Feb 2025 17:19:00 -0500 Subject: [PATCH 09/14] better MultiDocRef docs --- src/MultiDocumenter.jl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index 1fcfd5ac..1c9f1c23 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -43,7 +43,8 @@ users can implement their own custom components. abstract type DropdownComponent end """ - struct MultiDocRef + struct MultiDocRef <: DropdownComponent + MultiDocRef(; upstream, name, path, giturl = "", branch = "gh-pages", fix_canonical_url = true) Represents one set of docs that will get an entry in the MultiDocumenter navigation. From 5ddcfc9272ac6d75db853ac9c23b0168f472b0d0 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Wed, 26 Feb 2025 11:34:26 -0500 Subject: [PATCH 10/14] Update src/renderers.jl Co-authored-by: Sebastian Pfitzner --- src/renderers.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/renderers.jl b/src/renderers.jl index 7aefd83e..66221213 100644 --- a/src/renderers.jl +++ b/src/renderers.jl @@ -38,11 +38,11 @@ end function render(c::Link, doc, thispage, prettyurls) # class nav-link nav-item makes the formatting correct - # _target="blank" opens the link in a new tab + # target="_blank" opens the link in a new tab # TODO: add "external link" icon after, either chain or arrow exiting box. # TODO: allow internal links return @htl """ - $(c.text) + $(c.text) """ end From c2b0f076e0f714c6e64ad4585898ee569b4f4047 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Wed, 26 Feb 2025 11:35:21 -0500 Subject: [PATCH 11/14] add an `isexternal` field to Link --- src/MultiDocumenter.jl | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index 1c9f1c23..fc422665 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -83,16 +83,18 @@ function MultiDocRef(; end """ - Link([text::String], link::String) <: DropdownComponent + Link([text::String], link::String, [isexternal::Bool]) <: DropdownComponent Represents a link to an external site. """ struct Link <: MultiDocumenter.DropdownComponent text::String link::String + isexternal::Bool end Link(link::String) = Link(link, link) +Link(text::String, link::String) = Link(text, string, true #=isexternal=#) # TODO: add check / test struct DropdownNav name::String From 2c34b809a4f4ea978a400634e151febc1e2737af Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Wed, 26 Feb 2025 11:37:27 -0500 Subject: [PATCH 12/14] implement the automated check we discussed --- src/MultiDocumenter.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index fc422665..db7ffc9a 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -94,7 +94,7 @@ struct Link <: MultiDocumenter.DropdownComponent end Link(link::String) = Link(link, link) -Link(text::String, link::String) = Link(text, string, true #=isexternal=#) # TODO: add check / test +Link(text::String, link::String) = Link(text, link, contains(link, "//") #=isexternal=#) # TODO: add check / test struct DropdownNav name::String From e8e8f8e61e450a88d623412bb14bc90bfccf404c Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Wed, 26 Feb 2025 11:40:09 -0500 Subject: [PATCH 13/14] Run formatter --- docs/make.jl | 5 +---- src/MultiDocumenter.jl | 2 +- test/runtests.jl | 5 +---- 3 files changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 7249b4a0..dfc83730 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -87,10 +87,7 @@ docs = [ name = "JuliaInterpreter", giturl = "https://github.com/JuliaDebug/JuliaInterpreter.jl.git", ), - MultiDocumenter.Link( - "Lux", - "https://github.com/avik-pal/Lux.jl", - ), + MultiDocumenter.Link("Lux", "https://github.com/avik-pal/Lux.jl"), ], ), MultiDocumenter.Column( diff --git a/src/MultiDocumenter.jl b/src/MultiDocumenter.jl index db7ffc9a..cb085d87 100644 --- a/src/MultiDocumenter.jl +++ b/src/MultiDocumenter.jl @@ -94,7 +94,7 @@ struct Link <: MultiDocumenter.DropdownComponent end Link(link::String) = Link(link, link) -Link(text::String, link::String) = Link(text, link, contains(link, "//") #=isexternal=#) # TODO: add check / test +Link(text::String, link::String) = Link(text, link, contains(link, "//")) struct DropdownNav name::String diff --git a/test/runtests.jl b/test/runtests.jl index d5e041e9..dfc60334 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -54,10 +54,7 @@ docs = [ name = "Lux", giturl = "https://github.com/avik-pal/Lux.jl", ), - MultiDocumenter.Link( - "JuliaHub", - "https://juliahub.com", - ), + MultiDocumenter.Link("JuliaHub", "https://juliahub.com"), ], ), MultiDocumenter.Column( From cfdeff59b8f7f7eedf066bb86ba9a4af9dce5aed Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Wed, 26 Feb 2025 16:39:39 -0500 Subject: [PATCH 14/14] use the external field of link to determine new tab or same tab Co-authored-by: Sebastian Pfitzner --- src/renderers.jl | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/renderers.jl b/src/renderers.jl index 66221213..ee4f6286 100644 --- a/src/renderers.jl +++ b/src/renderers.jl @@ -40,9 +40,8 @@ function render(c::Link, doc, thispage, prettyurls) # class nav-link nav-item makes the formatting correct # target="_blank" opens the link in a new tab # TODO: add "external link" icon after, either chain or arrow exiting box. - # TODO: allow internal links return @htl """ - $(c.text) + $(c.text) """ end