From 2ca483743c21ece09235ddbfa5215703c22a1f2f Mon Sep 17 00:00:00 2001 From: Matthew Fishman Date: Sat, 25 Apr 2026 10:39:12 -0400 Subject: [PATCH] Fix Documentation build broken by README port The `examples/README.jl` shipped in #21 split the runnable Julia into two bare-Julia code blocks (the imports and the index/`@visualize` setup) separated by prose. Literate's `DocumenterFlavor` turned each into its own `@example index` block in `docs/src/index.md`. State did not propagate across the two blocks on the Documentation CI runner, which left `Index` undefined when the second block ran. Also, `docs/Project.toml` was missing `ITensors` as a dependency, so even a single-block setup couldn't have resolved the import. - Consolidate the runnable Julia in `examples/README.jl` into one bare block so it lands as a single `@example index` block in `index.md`, removing the cross-block-state assumption entirely. Both `@visualize` calls now sit together in that block; the description prose was rearranged so the lead-in still flows naturally. - Add `ITensors` to `docs/Project.toml` deps + compat (matching the root `Project.toml` compat range) so `using ITensors: Index, random_itensor` resolves during the Documenter build. Verified locally: `docs/make.jl` now builds without errors, and `include("examples/README.jl")` from the test environment still runs the example through the no-op default backend. Co-Authored-By: Claude Opus 4.7 (1M context) --- Project.toml | 2 +- README.md | 29 ++++++++--------------------- docs/Project.toml | 2 ++ examples/README.jl | 27 ++++++++------------------- 4 files changed, 19 insertions(+), 41 deletions(-) diff --git a/Project.toml b/Project.toml index d7e5e2b..e7f4395 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "ITensorVisualizationBase" uuid = "cd2553d2-8bef-4d93-8a38-c62f17d5ad23" -version = "0.1.16" +version = "0.1.17" authors = ["Matthew Fishman and contributors"] [workspace] diff --git a/README.md b/README.md index 33f50a5..57e6dc4 100644 --- a/README.md +++ b/README.md @@ -49,25 +49,15 @@ or `ITensorGLMakie`. The main purpose is to use it with the [ITensors.jl](https://github.com/ITensor/ITensors.jl) package to view and debug tensor network contractions, for example: +Load a visualization backend (such as `using ITensorUnicodePlots`) to actually render +the diagrams; without one, the `@visualize` macro is a no-op so that the example below +still runs in test environments that do not have a backend installed. +`ITensorVisualizationBase` handles the logic of switching between backends. + ````julia using ITensorVisualizationBase: ITensorVisualizationBase, @visualize using ITensors: Index, random_itensor -```` - -Load a visualization backend, which will reexport the interface of -`ITensorVisualizationBase` automatically: -```julia -using ITensorUnicodePlots -``` - -(we leave the `using ITensorUnicodePlots` line out of this example so it can run in -test environments that do not have the backend installed.) - -`ITensorVisualizationBase` handles the logic of switching between backends: - -````julia @show ITensorVisualizationBase.get_backend() - i = Index(2, "i") j = Index(10, "j") k = Index(40, "k") @@ -77,9 +67,10 @@ A = random_itensor(i, j, k) B = random_itensor(i, j, l, m) C = random_itensor(k, l) ABC = @visualize A * B * C +ABC_tags = @visualize A * B * C edge_labels = (tags = true,) ```` -With the `ITensorUnicodePlots` backend loaded, this outputs: +With `ITensorUnicodePlots` loaded, the first `@visualize` call outputs: ```julia ITensorVisualizationBase.get_backend() = ITensorVisualizationBase.Backend{:UnicodePlots}()⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ @@ -106,11 +97,7 @@ ITensorVisualizationBase.get_backend() = ITensorVisualizationBase.Backend{:Unico ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ``` -You can show the visualization with tags with: - -````julia -ABC_tags = @visualize A * B * C edge_labels = (tags = true,) -```` +And the second `@visualize` call (with `edge_labels = (tags = true,)`) outputs: ```julia ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ diff --git a/docs/Project.toml b/docs/Project.toml index 1b4c563..10392d3 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -2,6 +2,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" ITensorFormatter = "b6bf39f1-c9d3-4bad-aad8-593d802f65fd" ITensorVisualizationBase = "cd2553d2-8bef-4d93-8a38-c62f17d5ad23" +ITensors = "9136182c-28ba-11e9-034c-db9fb085ebd5" [sources.ITensorVisualizationBase] path = ".." @@ -10,3 +11,4 @@ path = ".." Documenter = "1" ITensorFormatter = "0.2.27" ITensorVisualizationBase = "0.1" +ITensors = "0.7, 0.8, 0.9" diff --git a/examples/README.jl b/examples/README.jl index fd5e652..2b1bf4c 100644 --- a/examples/README.jl +++ b/examples/README.jl @@ -51,24 +51,14 @@ julia> Pkg.add("ITensorVisualizationBase") # [ITensors.jl](https://github.com/ITensor/ITensors.jl) package to view and debug tensor # network contractions, for example: +# Load a visualization backend (such as `using ITensorUnicodePlots`) to actually render +# the diagrams; without one, the `@visualize` macro is a no-op so that the example below +# still runs in test environments that do not have a backend installed. +# `ITensorVisualizationBase` handles the logic of switching between backends. + using ITensorVisualizationBase: ITensorVisualizationBase, @visualize using ITensors: Index, random_itensor - -# Load a visualization backend, which will reexport the interface of -# `ITensorVisualizationBase` automatically: -#= -```julia -using ITensorUnicodePlots -``` -=# - -# (we leave the `using ITensorUnicodePlots` line out of this example so it can run in -# test environments that do not have the backend installed.) - -# `ITensorVisualizationBase` handles the logic of switching between backends: - @show ITensorVisualizationBase.get_backend() - i = Index(2, "i") j = Index(10, "j") k = Index(40, "k") @@ -78,8 +68,9 @@ A = random_itensor(i, j, k) B = random_itensor(i, j, l, m) C = random_itensor(k, l) ABC = @visualize A * B * C +ABC_tags = @visualize A * B * C edge_labels = (tags = true,) -# With the `ITensorUnicodePlots` backend loaded, this outputs: +# With `ITensorUnicodePlots` loaded, the first `@visualize` call outputs: #= ```julia @@ -108,9 +99,7 @@ ITensorVisualizationBase.get_backend() = ITensorVisualizationBase.Backend{:Unico ``` =# -# You can show the visualization with tags with: - -ABC_tags = @visualize A * B * C edge_labels = (tags = true,) +# And the second `@visualize` call (with `edge_labels = (tags = true,)`) outputs: #= ```julia