Fix and update documentation

NEWS.md

@@ -3,6 +3,7 @@
 
 ## v0.5.0
 
+- Improved documentation
 - `TypstError` renamed to `TypstCommandError`
 - `TypstContext`
 - `preamble` and `set_preamble` replaced by `context::TypstContext` and `set_context`

docs/make.jl

@@ -7,8 +7,7 @@ using .DocMeta: setdocmeta!
 using LaTeXStrings: LaTeXString
 using Luxor: Drawing, finish, julia_blue, julia_green, julia_purple, julia_red, rect, sethue
 using Markdown: MD
-using Typstry: Strings, preamble
-using .Strings: examples, _show_typst, enclose, join_with, typst_mime
+using Typstry: _show_typst, enclose, examples, join_with, preamble, typst_mime
 using Typstry
 
 const assets = joinpath(@__DIR__, "source", "assets")
@@ -52,7 +51,7 @@ finish()
 open(template; truncate = true) do file
     println(file, "\n#import table: cell, header\n\n#let template(document) = {")
 
-    for x in split(preamble, "\n")
+    for x in split(preamble(context), "\n")
         println(file, "    ", x[2:end])
     end
 
@@ -114,7 +113,7 @@ for (package, examples) in append!([("Typstry", examples)], zip(extensions, _exa
 
             print(file, "\",", v isa Union{Vector, Matrix} ? "\n        " : " ")
             join_with(file, modes, ", ") do file, mode
-                _show_typst(IOContext(file, :mode => code), String(TypstString(v; mode)))
+                _show_typst(file, String(TypstString(v; mode)); mode = code)
                 print(file, ", [")
                 enclose(_show_typst, file, TypstString(v; mode, depth = 2), (
                     if mode == code; ("#", "")
@@ -132,16 +131,12 @@ for (package, examples) in append!([("Typstry", examples)], zip(extensions, _exa
     run(TypstCommand(["compile", "--font-path=" * julia_mono, "--format=svg", path]))
 end
 
-makedocs(; modules,
-    format = Documenter.HTML(edit_link = "main"),
-    pages = [
-        "Typstry.jl" => "index.md",
-        pages("tutorials", ["getting_started"]),
-        pages("guides", ["typst_formatting_examples", "the_julia_to_typst_interface", "package_interoperability"]),
-        pages("references", ["strings", "commands", "package_extensions", "internals"])
-    ],
-    sitename = "Typstry.jl",
-    source = "source"
-)
+makedocs(; modules, format = Documenter.HTML(edit_link = "main"), pages = [
+    "Typstry.jl" => "index.md",
+    pages("tutorials", ["getting_started"]),
+    pages("guides", [
+        "typst_formatting_examples", "the_julia_to_typst_interface", "package_interoperability"
+    ]), pages("references", ["strings", "commands", "utilities", "package_extensions", "internals"])
+], sitename = "Typstry.jl", source = "source")
 
 deploydocs(; devurl = "development", repo = "github.com/jakobjpeters/Typstry.jl.git")

docs/source/guides/package_interoperability.md

@@ -5,9 +5,12 @@ This guide illustrates how to use Typstry.jl in compatible notebooks and package
 
 ## Notebooks
 
-IJulia.jl, Pluto.jl, and QuartoNotebookRunner.jl each [`render`](@ref) [`Typst`](@ref)s and [`TypstText`](@ref)s.
-Pluto.jl and QuartoNotebookRunner.jl also `render` [`TypstString`](@ref)s,
-whereas IJulia.jl will support them in its next feature release.
+IJulia.jl, Pluto.jl, and QuartoNotebookRunner.jl each display
+[`TypstString`](@ref)s, [`TypstText`](@ref)s, and [`Typst`](@ref)s using
+`show` with the `application/pdf`, `image/png`, and `image/svg+xml` `MIME` types.
+
+!!! tip
+    Use [`set_context`](@ref) to customize the default formatting in these environments.
 
 ## Typst Packages
 

docs/source/references/commands.md

@@ -1,44 +1,13 @@
 
 # Commands
 
-```@eval
-using Markdown, Typstry
-Markdown.parse("This reference documents " * lowercasefirst(split(string(@doc Typstry.Commands), "\n")[5]))
-```
-
-## `Typstry`
+This reference documents how to interact with the Typst compiler.
 
 ```@docs
-TypstCommand
 TypstCommandError
+TypstCommand
 @typst_cmd
 julia_mono
-preamble
 render
-set_preamble
 typst
 ```
-
-## `Base`
-
-```@docs
-==
-addenv
-detach
-eltype
-firstindex
-getindex
-hash
-ignorestatus
-iterate(::TypstCommand)
-keys
-lastindex
-length
-run
-setcpuaffinity
-setenv
-show(::IO, ::MIME"text/plain", ::TypstCommand)
-show(::IO, ::MIME"text/plain", ::TypstCommandError)
-show(::IO, ::Union{MIME"application/pdf", MIME"image/png", MIME"image/svg+xml"}, ::Union{Typst, TypstString, TypstText})
-showerror(::IO, ::TypstCommandError)
-```

docs/source/references/internals.md

@@ -3,52 +3,50 @@
 
 This reference documents non-public utilities.
 
-```@docs
-Typstry.compile_workload
-Typstry.unwrap
-```
-
-## Strings
+!!! info
+    A Dates.jl package extension would currently print warnings during precompilation.
+    See also the [Julia issue #52511](https://github.com/JuliaLang/julia/issues/52511)
 
 ```@docs
-Typstry.Strings
-Typstry.Strings.examples
-Typstry.Strings.typst_mime
-Typstry.Strings.backticks
-Typstry.Strings.block
-Typstry.Strings.code_mode
-Typstry.Strings.depth
-Typstry.Strings.enclose
-Typstry.Strings.escape
-Typstry.Strings.indent
-Typstry.Strings.join_with
-Typstry.Strings.math_mode
-Typstry.Strings.math_pad
-Typstry.Strings.mode
-Typstry.Strings.parenthesize
-Typstry.Strings.show_array
-Typstry.Strings.show_parameters
-Typstry.Strings.show_raw
-Typstry.Strings.show_vector
+Typstry.examples
 ```
 
-### Dates.jl
-
-!!! info
-    A Dates.jl package extension would currently print warnings during precompilation.
-    See also the [Julia issue #52511](https://github.com/JuliaLang/julia/issues/52511)
+## Utilities.jl
 
 ```@docs
-Typstry.Strings.date_time
-Typstry.Strings.duration
-Typstry.Strings.dates
+Typstry.typst_mime
+Typstry.apply
+Typstry.compile_workload
+Typstry.code_mode
+Typstry.date_time
+Typstry.dates
+Typstry.default_context
+Typstry.duration
+Typstry.enclose
+Typstry.escape
+Typstry.indent
+Typstry.format
+Typstry.join_with
+Typstry.math_mode
+Typstry.math_pad
+Typstry.merge_contexts!
+Typstry.show_array
+Typstry.show_parameters
+Typstry.show_raw
+Typstry.show_vector
+Typstry.typst_context
+Typstry.unwrap
 ```
 
-## Commands
+## Strings
 
 ```@docs
-Typstry.Commands
-Typstry.Commands.default_preamble
-Typstry.Commands.apply
-Typstry.Commands.format
+Typstry.backticks
+Typstry.base_type
+Typstry.block
+Typstry.depth
+Typstry.mode
+Typstry.parenthesize
+Typstry.preamble
+Typstry.tab_size
 ```

docs/source/references/package_extensions.md

@@ -7,11 +7,11 @@ This reference documents the lazily-loaded implementations of
 ## LaTeXStrings.jl
 
 ```@docs
-show_typst(::Any, ::LaTeXStrings.LaTeXString)
+show_typst(::Any, ::Any, ::LaTeXStrings.LaTeXString)
 ```
 
 ## Markdown.jl
 
 ```@docs
-show_typst(::Any, ::Markdown.MD)
+show_typst(::Any, ::Any, ::Markdown.MD)
 ```

docs/source/references/strings.md

@@ -1,27 +1,15 @@
 
 # Strings
 
-```@eval
-using Markdown, Typstry
-Markdown.parse("This reference documents " * lowercasefirst(split(string(@doc Typstry.Strings), "\n")[5]))
-```
+This reference documents formatting Julia values into Typst source text.
 
 ```@docs
-ContextError
-Mode
-Typst
 TypstString
 TypstText
+Typst
 @typst_str
-code
-markup
-math
-context
-show_typst(::Any, ::AbstractChar)
-```
-
-```@docs
-show(::IO, ::MIME"text/plain", ::ContextError)
-show(::IO, ::MIME"text/typst", ::Typst)
-showerror(::IO, ::ContextError)
+show_typst
+show_typst(::Any, ::Any, ::TypstString)
+show_typst(::Any, ::Any, ::TypstText)
+show_typst(::Any, ::Any, ::Typst)
 ```

docs/source/references/utilities.md

@@ -0,0 +1,13 @@
+
+# Utilities
+
+```@docs
+Mode
+code
+markup
+math
+ContextError
+TypstContext
+context
+set_context
+```

docs/source/tutorials/getting_started.md

@@ -40,7 +40,7 @@ typst"$ π approx 3.141592653589793 $"
 
 ## Commands
 
-Use the Typst command-line interface by [`run`](@ref)ning a
+Use the Typst command-line interface by `run`ning a
 [`TypstCommand`](@ref) created with its constructor or [`@typst_cmd`](@ref).
 
 ```jldoctest 1

ext/LaTeXStringsExtension.jl

@@ -6,9 +6,11 @@ using LaTeXStrings: LaTeXString, @L_str
 using Typstry: compile_workload, show_raw
 
 """
-    show_typst(io, ::LaTeXString)
+    show_typst(::IO, ::TypstContext, ::LaTeXString)
 
-Print in Typst format for LaTeXStrings.jl.
+Print a raw text block in Typst format.
+
+See also [`TypstContext`](@ref Typstry.TypstContext).
 
 | Type          | Settings                                 | Parameters |
 |:--------------|:-----------------------------------------|:-----------|

ext/MarkdownExtension.jl

@@ -6,9 +6,11 @@ using Markdown: MD, @md_str
 using Typstry: compile_workload, show_raw
 
 """
-    show_typst(io, ::Markdown.MD)
+    show_typst(::IO, ::TypstContext, ::Markdown.MD)
 
-Print in Typst format for Markdown.jl.
+Print a raw text block in Typst format.
+
+See also [`TypstContext`](@ref Typstry.TypstContext).
 
 | Type          | Settings                                 | Parameters |
 |:--------------|:-----------------------------------------|:-----------|