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)
+    # Keep Plots on a non-interactive backend for CI and test runs.
+    get!(ENV, "GKSwstype", "100")
+
+    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",
+        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,
+        ),
+    )
+
+    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))

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