Add doctest integration to test suite and fix docs build

README.md

@@ -58,6 +58,15 @@ import Pkg
 Pkg.add("QUBOTools")
 ```
 
+### Build the Documentation Locally
+
+From the repository root, use:
+
+```bash
+julia --project=docs -e 'using Pkg; Pkg.develop(path=pwd()); Pkg.instantiate()'
+julia --project=docs docs/make.jl --skip-deploy
+```
+
 ### Basic Usage
 
 ```julia

docs/Project.toml

@@ -1,10 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-DocumenterDiagrams = "a106ebf2-4182-4cba-90d4-44cd3cc36e85"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 QUBOTools = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
 
 [compat]
 Documenter = "1"
-DocumenterDiagrams = "1"
 Plots = "~1.38"

docs/build.jl

@@ -0,0 +1,57 @@
+using Documenter
+using QUBOTools
+
+const DOCS_PAGES = [
+    "Home" => "index.md",
+    "Manual" => [
+        "Introduction"             => "manual/1-start.md",
+        "Mathematical Formulation" => "manual/2-math.md",
+        "Basic Usage"              => "manual/3-usage.md",
+        "Models"                   => "manual/4-models.md",
+        "File Formats"             => "manual/5-formats.md",
+        "Solutions"                => "manual/6-solutions.md",
+        "Analysis"                 => "manual/7-analysis.md",
+    ],
+    "Formats" => [
+        "BQPJSON"  => "formats/bqpjson.md",
+        "MiniZinc" => "formats/minizinc.md",
+        "QUBin"    => "formats/qubin.md",
+        "Qubist"   => "formats/qubist.md",
+        "QUBO"     => "formats/qubo.md",
+        "Rudy"     => "formats/rudy.md",
+    ],
+    "API Reference" => "api.md",
+]
+
+function build_docs(; deploy::Bool = false)
+    DocMeta.setdocmeta!(QUBOTools, :DocTestSetup, :(using QUBOTools); recursive = true)
+
+    # Keep Plots on a non-interactive backend only while Documenter runs.
+    withenv("GKSwstype" => "100") do
+        makedocs(;
+            modules  = [QUBOTools, QUBOTools.PBO],
+            doctest  = true,
+            clean    = true,
+            sitename = "QUBOTools.jl",
+            authors  = "Pedro Maciel Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David E. Bernal Neira",
+            source   = joinpath(@__DIR__, "src"),
+            build    = joinpath(@__DIR__, "build"),
+            workdir  = @__DIR__,
+            warnonly = [:missing_docs, :docs_block],
+            pages    = DOCS_PAGES,
+            format   = Documenter.HTML(
+                assets           = ["assets/extra_styles.css", "assets/favicon.ico"],
+                mathengine       = Documenter.KaTeX(),
+                sidebar_sitename = false,
+            ),
+        )
+    end
+
+    if deploy
+        deploydocs(repo = raw"github.com/JuliaQUBO/QUBOTools.jl.git", push_preview = true)
+    else
+        @info "Skipping deployment"
+    end
+
+    return nothing
+end

docs/make.jl

@@ -1,48 +1,3 @@
-using Documenter
-using DocumenterDiagrams
-using QUBOTools
+include("build.jl")
 
-# Set up to run docstrings with jldoctest
-DocMeta.setdocmeta!(QUBOTools, :DocTestSetup, :(using QUBOTools); recursive = true)
-
-makedocs(;
-    modules  = [QUBOTools, QUBOTools.PBO],
-    doctest  = true,
-    clean    = true,
-    sitename = "QUBOTools.jl",
-    authors  = "Pedro Maciel Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David E. Bernal Neira",
-    workdir  = @__DIR__,
-    warnonly = [:missing_docs, :docs_block],
-    pages    = [
-        "Home" => "index.md",
-        "Manual" => [
-            "Introduction"             => "manual/1-start.md",
-            "Mathematical Formulation" => "manual/2-math.md",
-            "Basic Usage"              => "manual/3-usage.md",
-            "Models"                   => "manual/4-models.md",
-            "File Formats"             => "manual/5-formats.md",
-            "Solutions"                => "manual/6-solutions.md",
-            "Analysis"                 => "manual/7-analysis.md",
-        ],
-        "Formats" => [
-            "BQPJSON"  => "formats/bqpjson.md",
-            "MiniZinc" => "formats/minizinc.md",
-            "QUBin"    => "formats/qubin.md",
-            "Qubist"   => "formats/qubist.md",
-            "QUBO"     => "formats/qubo.md",
-            "Rudy"     => "formats/rudy.md",
-        ],
-        "API Reference" => "api.md",
-    ],
-    format   = Documenter.HTML(
-        assets           = ["assets/extra_styles.css", "assets/favicon.ico"],
-        mathengine       = Documenter.KaTeX(),
-        sidebar_sitename = false,
-    ),
-)
-
-if "--skip-deploy" ∈ ARGS
-    @warn "Skipping deployment"
-else
-    deploydocs(repo = raw"github.com/JuliaQUBO/QUBOTools.jl.git", push_preview = true)
-end
+build_docs(; deploy = !("--skip-deploy" ∈ ARGS))

docs/src/manual/7-analysis.md

@@ -6,6 +6,20 @@
 using Random
 
 Random.seed!(0)
+
+const render_visualization = let
+    # GitHub's Windows runner intermittently fails to load GR artifacts.
+    # Keep the examples executable there by rendering the recipe object instead.
+    if Sys.iswindows() && get(ENV, "CI", "false") == "true"
+        @info "Skipping plot rendering on Windows CI; showing the recipe object instead."
+        identity
+    else
+        @eval import Plots
+        obj -> Plots.plot(obj)
+    end
+end
+
+nothing
 ```
 
 ```@example analysis
@@ -20,15 +34,13 @@ model = QUBOTools.generate(QUBOTools.SK(n))
 ### Model Density
 
 ```@example analysis
-using Plots
-
-plot(QUBOTools.ModelDensityPlot(model))
+render_visualization(QUBOTools.ModelDensityPlot(model))
 ```
 
 ### System Layout
 
 ```@example analysis
-plot(QUBOTools.SystemLayoutPlot(model))
+render_visualization(QUBOTools.SystemLayoutPlot(model))
 ```
 
 ## Solutions
@@ -60,11 +72,11 @@ solution = magical_solution_method(model)
 ```@example analysis
 λ = minimum(QUBOTools.value, solution) # threshold
 
-plot(QUBOTools.EnergyFrequencyPlot(solution, λ))
+render_visualization(QUBOTools.EnergyFrequencyPlot(solution, λ))
 ```
 
 ### Energy Distribution
 
 ```@example analysis
-plot(QUBOTools.EnergyDistributionPlot(solution))
+render_visualization(QUBOTools.EnergyDistributionPlot(solution))
 ```

test/Project.toml

@@ -1,12 +1,17 @@
 [deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
+Documenter = "1"
+Plots = "~1.38"
 RecipesBase = "1"

test/integration/docs.jl

@@ -0,0 +1,16 @@
+using Test
+using QUBOTools
+
+const __DOCS_PATH__ = normpath(joinpath(@__DIR__, "..", "..", "docs"))
+
+include(joinpath(__DOCS_PATH__, "build.jl"))
+
+function test_docs()
+    @testset "▶ Documentation Tests" verbose = true begin
+        # Run the full docs build so docstrings and manual @example blocks stay valid.
+        build_docs(; deploy = false)
+        @test isfile(joinpath(__DOCS_PATH__, "build", "index.html"))
+    end
+
+    return nothing
+end

test/integration/integration.jl

@@ -1,4 +1,5 @@
 include("ext/ext.jl")
+include("docs.jl")
 
 function test_foreign()
     if run_foreign_tests()
@@ -15,6 +16,7 @@ end
 function test_integration()
     @testset "⊚ ⊚ Integration Tests" verbose = true begin
         test_extensions()
+        test_docs()
         test_foreign()
     end