Skip to content

Commit a7639a1

Browse files
ocotsocots
committed
foo
1 parent 157cdd5 commit a7639a1

File tree

1 file changed

+273
-0
lines changed

1 file changed

+273
-0
lines changed

‎test/test_documenter_reference.jl‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
using Test
2+
using CTBase
3+
using Documenter
4+
5+
module DocumenterReferenceTestMod
6+
7+
"""
8+
Simple documented function used to test source file detection and inclusion.
9+
"""
10+
myfun(x) = x
11+
12+
"""
13+
Function that should be kept by _iterate_over_symbols.
14+
"""
15+
keep(x) = x
16+
17+
"""
18+
Function that will be excluded via the `exclude` configuration.
19+
"""
20+
skip(x) = x
21+
22+
# No docstring: this function should be skipped by _iterate_over_symbols.
23+
no_doc(x) = x
24+
25+
"""
26+
Test submodule with a docstring but no associated source file information.
27+
Used to exercise include_without_source behaviour for modules.
28+
"""
29+
module SubModule
30+
end
31+
32+
abstract type AbstractFoo end
33+
34+
struct Foo <: AbstractFoo
35+
x::Int
36+
end
37+
38+
const MYCONST = 42
39+
40+
end
41+
42+
function test_documenter_reference()
43+
DR = DocumenterReference
44+
45+
@testset "reset_config! clears CONFIG" begin
46+
DR.reset_config!()
47+
@test isempty(DR.CONFIG)
48+
end
49+
50+
@testset "_default_basename and _build_page_path" begin
51+
@test DR._default_basename("manual", true, true) == "manual"
52+
@test DR._default_basename("", true, true) == "api"
53+
@test DR._default_basename("", true, false) == "public"
54+
@test DR._default_basename("", false, true) == "private"
55+
56+
@test DR._build_page_path("api", "public") == "api/public"
57+
@test DR._build_page_path(".", "public") == "public"
58+
@test DR._build_page_path("", "public") == "public"
59+
end
60+
61+
@testset "_classify_symbol and _to_string" begin
62+
using .DocumenterReferenceTestMod
63+
64+
@test DR._classify_symbol(nothing, "@mymacro") == DR.DOCTYPE_MACRO
65+
@test DR._classify_symbol(DocumenterReferenceTestMod.SubModule, "SubModule") == DR.DOCTYPE_MODULE
66+
@test DR._classify_symbol(DocumenterReferenceTestMod.AbstractFoo, "AbstractFoo") == DR.DOCTYPE_ABSTRACT_TYPE
67+
@test DR._classify_symbol(DocumenterReferenceTestMod.Foo, "Foo") == DR.DOCTYPE_STRUCT
68+
@test DR._classify_symbol(DocumenterReferenceTestMod.myfun, "myfun") == DR.DOCTYPE_FUNCTION
69+
@test DR._classify_symbol(DocumenterReferenceTestMod.MYCONST, "MYCONST") == DR.DOCTYPE_CONSTANT
70+
71+
@test DR._to_string(DR.DOCTYPE_ABSTRACT_TYPE) == "abstract type"
72+
@test DR._to_string(DR.DOCTYPE_CONSTANT) == "constant"
73+
@test DR._to_string(DR.DOCTYPE_FUNCTION) == "function"
74+
@test DR._to_string(DR.DOCTYPE_MACRO) == "macro"
75+
@test DR._to_string(DR.DOCTYPE_MODULE) == "module"
76+
@test DR._to_string(DR.DOCTYPE_STRUCT) == "struct"
77+
end
78+
79+
@testset "_get_source_file" begin
80+
using .DocumenterReferenceTestMod
81+
82+
path = DR._get_source_file(DocumenterReferenceTestMod, :myfun, DR.DOCTYPE_FUNCTION)
83+
@test path === abspath(@__FILE__)
84+
85+
const_path = DR._get_source_file(DocumenterReferenceTestMod, :MYCONST, DR.DOCTYPE_CONSTANT)
86+
@test const_path === nothing
87+
end
88+
89+
@testset "_iterate_over_symbols filtering" begin
90+
using .DocumenterReferenceTestMod
91+
92+
current_module = DocumenterReferenceTestMod
93+
modules = Dict(current_module => Any[])
94+
exclude = Set{Symbol}([:skip])
95+
sort_by(x) = x
96+
source_files = String[]
97+
98+
config = DR._Config(
99+
current_module,
100+
"api",
101+
modules,
102+
sort_by,
103+
exclude,
104+
true,
105+
true,
106+
"API Reference",
107+
"API Reference",
108+
source_files,
109+
"api",
110+
false,
111+
Module[],
112+
)
113+
114+
symbols = [
115+
:keep => DR.DOCTYPE_FUNCTION,
116+
:skip => DR.DOCTYPE_FUNCTION,
117+
:no_doc => DR.DOCTYPE_FUNCTION,
118+
]
119+
120+
seen = Symbol[]
121+
DR._iterate_over_symbols(config, symbols) do key, type
122+
push!(seen, key)
123+
end
124+
125+
@test :keep in seen
126+
@test :skip ∉ seen
127+
@test :no_doc ∉ seen
128+
end
129+
130+
@testset "_iterate_over_symbols with source_files and include_without_source" begin
131+
using .DocumenterReferenceTestMod
132+
133+
current_module = DocumenterReferenceTestMod
134+
modules = Dict(current_module => Any[])
135+
sort_by(x) = x
136+
allowed = [abspath(@__FILE__)]
137+
138+
# Case 1: Only symbols whose source is in `allowed` are kept
139+
config1 = DR._Config(
140+
current_module,
141+
"api",
142+
modules,
143+
sort_by,
144+
Set{Symbol}(),
145+
true,
146+
true,
147+
"API Reference",
148+
"API Reference",
149+
allowed,
150+
"api",
151+
false,
152+
Module[],
153+
)
154+
155+
symbols1 = [
156+
:myfun => DR.DOCTYPE_FUNCTION,
157+
]
158+
159+
seen1 = Symbol[]
160+
DR._iterate_over_symbols(config1, symbols1) do key, type
161+
push!(seen1, key)
162+
end
163+
@test :myfun in seen1
164+
165+
# Case 2: Module symbols without source are kept only when include_without_source=true
166+
config2 = DR._Config(
167+
current_module,
168+
"api",
169+
modules,
170+
sort_by,
171+
Set{Symbol}(),
172+
true,
173+
true,
174+
"API Reference",
175+
"API Reference",
176+
allowed,
177+
"api",
178+
false,
179+
Module[],
180+
)
181+
182+
config3 = DR._Config(
183+
current_module,
184+
"api",
185+
modules,
186+
sort_by,
187+
Set{Symbol}(),
188+
true,
189+
true,
190+
"API Reference",
191+
"API Reference",
192+
allowed,
193+
"api",
194+
true,
195+
Module[],
196+
)
197+
198+
symbols_module = [
199+
:SubModule => DR.DOCTYPE_MODULE,
200+
]
201+
202+
seen2 = Symbol[]
203+
DR._iterate_over_symbols(config2, symbols_module) do key, type
204+
push!(seen2, key)
205+
end
206+
@test isempty(seen2)
207+
208+
seen3 = Symbol[]
209+
DR._iterate_over_symbols(config3, symbols_module) do key, type
210+
push!(seen3, key)
211+
end
212+
@test :SubModule in seen3
213+
end
214+
215+
@testset "automatic_reference_documentation configuration" begin
216+
DR.reset_config!()
217+
using .DocumenterReferenceTestMod
218+
219+
# Single-module, public-only
220+
pages1 = CTBase.automatic_reference_documentation(
221+
CTBase.DocumenterReferenceTag();
222+
subdirectory="ref",
223+
modules=[DocumenterReferenceTestMod],
224+
public=true,
225+
private=false,
226+
title="My API",
227+
)
228+
229+
@test length(DR.CONFIG) == 1
230+
cfg1 = DR.CONFIG[1]
231+
@test cfg1.current_module === DocumenterReferenceTestMod
232+
@test cfg1.subdirectory == "ref"
233+
@test cfg1.public == true
234+
@test cfg1.private == false
235+
@test cfg1.filename == "public"
236+
@test pages1 == "My API" => "ref/public.md"
237+
238+
# Both public and private pages
239+
DR.reset_config!()
240+
pages2 = CTBase.automatic_reference_documentation(
241+
CTBase.DocumenterReferenceTag();
242+
subdirectory="ref",
243+
modules=[DocumenterReferenceTestMod],
244+
public=true,
245+
private=true,
246+
title="All API",
247+
)
248+
249+
@test length(DR.CONFIG) == 1
250+
cfg2 = DR.CONFIG[1]
251+
@test cfg2.filename == "api"
252+
@test cfg2.public == true
253+
@test cfg2.private == true
254+
@test cfg2.title == "All API"
255+
@test first(pages2) == "All API" => [
256+
"Public" => "ref/public.md",
257+
"Private" => "ref/private.md",
258+
]
259+
260+
# public=false, private=false should error
261+
@test_throws ErrorException CTBase.automatic_reference_documentation(
262+
CTBase.DocumenterReferenceTag();
263+
subdirectory="ref",
264+
modules=[DocumenterReferenceTestMod],
265+
public=false,
266+
private=false,
267+
)
268+
end
269+
270+
@testset "Documenter.Selectors.order for APIBuilder" begin
271+
@test Documenter.Selectors.order(DR.APIBuilder) == 0.0
272+
end
273+
end

0 commit comments

Comments
 (0)