Define shared workflows for building docs and running tests

Project.toml

@@ -1,6 +1,6 @@
 name = "ITensorFormatter"
 uuid = "b6bf39f1-c9d3-4bad-aad8-593d802f65fd"
-version = "0.2.25"
+version = "0.2.26"
 authors = ["ITensor developers <support@itensor.org> and contributors"]
 
 [workspace]

docs/Project.toml

@@ -1,12 +1,10 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 ITensorFormatter = "b6bf39f1-c9d3-4bad-aad8-593d802f65fd"
-Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 
 [sources.ITensorFormatter]
 path = ".."
 
 [compat]
 Documenter = "1"
 ITensorFormatter = "0.2"
-Literate = "2"

docs/make.jl

@@ -5,7 +5,7 @@ DocMeta.setdocmeta!(
     ITensorFormatter, :DocTestSetup, :(using ITensorFormatter); recursive = true
 )
 
-include("make_index.jl")
+ITensorFormatter.make_index!(pkgdir(ITensorFormatter))
 
 makedocs(;
     modules = [ITensorFormatter],

src/ITensorFormatter.jl

@@ -1,7 +1,7 @@
 module ITensorFormatter
 
 if VERSION >= v"1.11.0-DEV.469"
-    let str = "public ITensorPkgFormatter, main"
+    let str = "public ITensorPkgFormatter, main, make_index!, make_readme!"
         eval(Meta.parse(str))
     end
 end

src/generate_readme.jl

@@ -1,11 +1,97 @@
 using Literate: Literate
 
+const GFM_ALERT_HEADER_MAP = Dict(
+    "> [!CAUTION]" => "!!! danger",
+    "> [!IMPORTANT]" => "!!! important",
+    "> [!NOTE]" => "!!! note",
+    "> [!TIP]" => "!!! tip",
+    "> [!WARNING]" => "!!! warning"
+)
+
+function _gfm_alerts(content::AbstractString)
+    lines = split(content, '\n')
+    output = String[]
+    in_alert = false
+    for line in lines
+        if haskey(GFM_ALERT_HEADER_MAP, line)
+            push!(output, GFM_ALERT_HEADER_MAP[line])
+            in_alert = true
+        elseif in_alert && startswith(line, ">")
+            if line == ">"
+                push!(output, "")
+            elseif startswith(line, "> ")
+                push!(output, "    " * line[3:end])
+            else
+                push!(output, line)
+            end
+        else
+            in_alert = false
+            push!(output, line)
+        end
+    end
+    return join(output, '\n')
+end
+
+function _ccq_logo_readme(content::AbstractString)
+    include_ccq_logo = """
+    <picture>
+      <source media="(prefers-color-scheme: dark)" width="20%" srcset="docs/src/assets/CCQ-dark.png">
+      <img alt="Flatiron Center for Computational Quantum Physics logo." width="20%" src="docs/src/assets/CCQ.png">
+    </picture>
+    """
+    return replace(content, "{CCQ_LOGO}" => include_ccq_logo)
+end
+
+function _ccq_logo_index(content::AbstractString)
+    include_ccq_logo = """
+    ```@raw html
+    <img class="display-light-only" src="assets/CCQ.png" width="20%" alt="Flatiron Center for Computational Quantum Physics logo."/>
+    <img class="display-dark-only" src="assets/CCQ-dark.png" width="20%" alt="Flatiron Center for Computational Quantum Physics logo."/>
+    ```
+    """
+    return replace(content, "{CCQ_LOGO}" => include_ccq_logo)
+end
+
+"""
+    make_readme!(pkgroot::AbstractString; inputfile, outputdir, flavor, name, postprocess)
+
+Generate `README.md` from `examples/README.jl` using `Literate.markdown`.
+"""
+function make_readme!(
+        pkgroot::AbstractString;
+        inputfile = joinpath(pkgroot, "examples", "README.jl"),
+        outputdir = pkgroot,
+        flavor = Literate.CommonMarkFlavor(),
+        name = "README",
+        postprocess = _ccq_logo_readme
+    )
+    Literate.markdown(inputfile, outputdir; flavor, name, postprocess)
+    return nothing
+end
+
+"""
+    make_index!(pkgroot::AbstractString; inputfile, outputdir, flavor, name, postprocess)
+
+Generate `docs/src/index.md` from `examples/README.jl` using `Literate.markdown`.
+"""
+function make_index!(
+        pkgroot::AbstractString;
+        inputfile = joinpath(pkgroot, "examples", "README.jl"),
+        outputdir = joinpath(pkgroot, "docs", "src"),
+        flavor = Literate.DocumenterFlavor(),
+        name = "index",
+        postprocess = _gfm_alerts ∘ _ccq_logo_index
+    )
+    Literate.markdown(inputfile, outputdir; flavor, name, postprocess)
+    return nothing
+end
+
 function isitensorpkg(path::AbstractString)
     return isdir(path) &&
         isfile(joinpath(path, "Project.toml")) &&
         isdir(joinpath(path, "src")) &&
         isdir(joinpath(path, "docs")) &&
-        isfile(joinpath(path, "docs", "make_readme.jl"))
+        isfile(joinpath(path, "examples", "README.jl"))
 end
 
 function generate_readmes!(paths::AbstractVector{<:AbstractString})
@@ -21,10 +107,8 @@ function generate_readme!(path::AbstractString)
         return nothing
     end
     try
-        cd(joinpath(path, "docs")) do
-            include(joinpath(pwd(), "make_readme.jl"))
-            return nothing
-        end
+        make_readme!(path)
+        return nothing
     catch e
         @warn "Failed to generate README: $e"
     end

src/precompile_workload.jl

@@ -10,6 +10,7 @@ using PrecompileTools: @compile_workload, @setup_workload
 
         # Minimal files so the formatter has something to do
         write(joinpath(tmp, "src", "Example.jl"), "module Example\nx=1\nend\n")
+        write(joinpath(tmp, "examples", "README.jl"), "# # Example\n")
         write(joinpath(tmp, "config.yaml"), "a: 1\nb: 2\n")
         write(
             joinpath(tmp, "Project.toml"),