Adds an options to use listings for code highlighting in LaTeX

.typos.toml

@@ -3,3 +3,6 @@ fo = "fo"
 ket = "ket"
 trun = "trun"
 varius = "varius"
+
+[files]
+extend-exclude = ["assets/latex/jlcode.sty"]

CHANGELOG.md

@@ -20,7 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-* Modules for `@example` environments are now generated by `eval`'ing an expression, rather than invoking the `Module` constructor, which is not recommended. (#2683)
+* Modules for `@example` environments are now generated by `eval`'ing an expression, rather than invoking the `Module` constructor, which is not recommended. ([#2683])
+* Fix handling of `expandfirst` entries containing slashes as path separators on Windows. ([#2804])
 * Changed the header crossref step to eagerly fail when encountering a non-unique header slug. ([#2668], [#2787])
 
   This is **potentially breaking** and may cause some documentation builds to fail.
@@ -2189,6 +2190,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2792]: https://github.com/JuliaDocs/Documenter.jl/issues/2792
 [#2793]: https://github.com/JuliaDocs/Documenter.jl/issues/2793
 [#2803]: https://github.com/JuliaDocs/Documenter.jl/issues/2803
+[#2804]: https://github.com/JuliaDocs/Documenter.jl/issues/2804
 [#2809]: https://github.com/JuliaDocs/Documenter.jl/issues/2809
 [#2812]: https://github.com/JuliaDocs/Documenter.jl/issues/2812
 [#2813]: https://github.com/JuliaDocs/Documenter.jl/issues/2813

assets/latex/documenter.sty

@@ -31,14 +31,7 @@
 %
 
 % listings
-\usepackage{minted}
-\setminted{
-    breaklines = true,
-    fontsize = \small,
-    frame = none,
-    bgcolor = codeblock-background,
-    rulecolor=codeblock-border,
-}
+
 %
 
 % tables

assets/latex/listings.sty

@@ -0,0 +1,9 @@
+\usepackage{listings}
+\lstset{
+    breaklines = true,
+    % fontsize = \small,
+    frame = none,
+    backgroundcolor = codeblock-background,
+    rulecolor= codeblock-border,
+    }
+\usepackage{jlcode}

assets/latex/minted.sty

@@ -0,0 +1,8 @@
+\usepackage{minted}
+\setminted{
+    breaklines = true,
+    fontsize = \small,
+    frame = none,
+    bgcolor = codeblock-background,
+    rulecolor=codeblock-border,
+}

assets/latex/preamble.tex

@@ -2,6 +2,7 @@
 \documentclass[oneside]{memoir}
 
 \usepackage{./documenter}
+\usepackage{./code_listings}
 \usepackage{./custom}
 
 %% Title Page

src/expander_pipeline.jl

@@ -38,7 +38,8 @@ function clear_modules!(d::Dict{Symbol, Any})
 end
 
 function expand(doc::Documenter.Document)
-    priority_pages = filter(doc.user.expandfirst) do src
+    expandfirst = map(normpath, doc.user.expandfirst)
+    priority_pages = filter(expandfirst) do src
         if src in keys(doc.blueprint.pages)
             return true
         else

src/latex/LaTeXWriter.jl

@@ -52,13 +52,16 @@ struct LaTeX <: Documenter.Writer
     platform::String
     version::String
     tectonic::Union{Cmd, String, Nothing}
+    code_listings::String
     function LaTeX(;
             platform = "native",
             version = get(ENV, "TRAVIS_TAG", ""),
-            tectonic = nothing
+            tectonic = nothing,
+            code_listings = "minted"
         )
         platform ∈ ("native", "tectonic", "docker", "none") || throw(ArgumentError("unknown platform: $platform"))
-        return new(platform, string(version), tectonic)
+        code_listings ∈ ("minted", "listings") || throw(ArgumentError("unknown code formatting package: $platform"))
+        return new(platform, string(version), tectonic, code_listings)
     end
 end
 
@@ -73,8 +76,9 @@ mutable struct Context{I <: IO} <: IO
     depth::Int
     filename::String # currently active source file
     doc::Documenter.Document
+    code_listings::String
 end
-Context(io, doc) = Context{typeof(io)}(io, false, Dict(), 1, "", doc)
+Context(io, doc, code_listings) = Context{typeof(io)}(io, false, Dict(), 1, "", doc, code_listings)
 
 _print(c::Context, args...) = Base.print(c.io, args...)
 _println(c::Context, args...) = Base.println(c.io, args...)
@@ -87,6 +91,9 @@ _hash(x) = string(hash(x))
 
 const STYLE = joinpath(dirname(@__FILE__), "..", "..", "assets", "latex", "documenter.sty")
 const DEFAULT_PREAMBLE_PATH = joinpath(dirname(@__FILE__), "..", "..", "assets", "latex", "preamble.tex")
+const JLCODE_PATH = joinpath(dirname(@__FILE__), "..", "..", "assets", "latex", "jlcode.sty")
+const LISTINGS_PATH = joinpath(dirname(@__FILE__), "..", "..", "assets", "latex", "listings.sty")
+const MINTED_PATH = joinpath(dirname(@__FILE__), "..", "..", "assets", "latex", "minted.sty")
 
 function hastex()
     try
@@ -122,7 +129,7 @@ function render(doc::Documenter.Document, settings::LaTeX = LaTeX())
         cd(joinpath(path, "build")) do
             fileprefix = latex_fileprefix(doc, settings)
             open("$(fileprefix).tex", "w") do io
-                context = Context(io, doc)
+                context = Context(io, doc, settings.code_listings)
                 writeheader(context, doc, settings)
                 for (title, filename, depth) in files(doc.user.pages)
                     context.filename = filename
@@ -147,6 +154,7 @@ function render(doc::Documenter.Document, settings::LaTeX = LaTeX())
                 writefooter(context, doc)
             end
             cp(STYLE, "documenter.sty")
+            settings.code_listings == "listings" && cp(JLCODE_PATH, "jlcode.sty")
 
             # compile .tex
             status = compile_tex(doc, settings, fileprefix)
@@ -258,6 +266,9 @@ function writeheader(io::IO, doc::Documenter.Document, settings::LaTeX)
     custom = joinpath(doc.user.root, doc.user.source, "assets", "custom.sty")
     isfile(custom) ? cp(custom, "custom.sty"; force = true) : touch("custom.sty")
 
+    cp(settings.code_listings == "minted" ? MINTED_PATH : LISTINGS_PATH, "code_listings.sty")
+
+
     custom_preamble_file = joinpath(doc.user.root, doc.user.source, "assets", "preamble.tex")
     if isfile(custom_preamble_file)
         # copy custom preamble.
@@ -538,23 +549,43 @@ function latex(io::Context, node::Node, code::MarkdownAST.CodeBlock)
     text = IOBuffer(code.code)
     code_code = repr(MIME"text/plain"(), ANSIColoredPrinters.PlainTextPrinter(text))
     escape = '⊻' ∈ code_code
-    _print(io, "\n\\begin{minted}")
-    if escape
-        _print(io, "[escapeinside=\\#\\%")
-    end
-    if language == "text/plain"
-        _print(io, escape ? "," : "[")
-        # Special-case the formatting of code outputs from Julia.
-        _println(io, "xleftmargin=-\\fboxsep,xrightmargin=-\\fboxsep,bgcolor=white,frame=single]{text}")
-    else
-        _println(io, escape ? "]{" : "{", language, "}")
-    end
-    if escape
-        _print_code_escapes_minted(io, code_code)
-    else
-        _print(io, code_code)
+    if io.code_listings == "minted"
+        _print(io, "\n\\begin{minted}")
+        if escape
+            _print(io, "[escapeinside=\\#\\%")
+        end
+        if language == "text/plain"
+            _print(io, escape ? "," : "[")
+            # Special-case the formatting of code outputs from Julia.
+            _println(io, "xleftmargin=-\\fboxsep,xrightmargin=-\\fboxsep,bgcolor=white,frame=single]{text}")
+        else
+            _println(io, escape ? "]{" : "{", language, "}")
+        end
+        if escape
+            _print_code_escapes_minted(io, code_code)
+        else
+            _print(io, code_code)
+        end
+        _println(io, "\n\\end{minted}\n")
+    elseif io.code_listings == "listings"
+        _print(io, "\n\\begin{lstlisting}")
+        _print(io, escape ? "[escapeinside=\\#\\%," : "[")
+        if language == "text/plain"
+            # _print(io, escape ? "," : "[")
+            # Special-case the formatting of code outputs from Julia.
+            _println(io, "]")
+        elseif language == "jlcon"
+            _println(io, "language=julia, style=jlcodestyle]")
+        else
+            _println(io, "]")
+        end
+        if escape
+            _print_code_escapes_minted(io, code_code)
+        else
+            _print(io, code_code)
+        end
+        _println(io, "\n\\end{lstlisting}\n")
     end
-    _println(io, "\n\\end{minted}\n")
     return
 end
 

test/doctests/doctests.jl

@@ -224,8 +224,8 @@ end
         @test is_same_as_file(output, rfile(8))
     end
 
-    # Here we try the default (strict = false) -- output should say that doctest failed, but
-    # success should still be true.
+    # Here we try the former default (strict = false, now warnonly = true) --
+    # output should say that doctest failed, but success should still be true.
     run_makedocs(["working.md"]; warnonly = true) do result, success, backtrace, output
         @test success
         @test is_same_as_file(output, rfile(11))

test/examples/make.jl

@@ -21,7 +21,7 @@ else
         "html", "html-meta-custom", "html-mathjax2-custom", "html-mathjax3", "html-mathjax3-custom",
         "html-local", "html-draft", "html-repo-git", "html-repo-nothing", "html-repo-error",
         "html-sizethreshold-defaults-fail", "html-sizethreshold-success", "html-sizethreshold-ignore-success", "html-sizethreshold-override-fail", "html-sizethreshold-ignore-success", "html-sizethreshold-ignore-fail",
-        "latex_texonly", "latex_simple_texonly", "latex_showcase_texonly", "html-pagesonly",
+        "latex_texonly", "latex_simple_texonly", "latex_listings_texonly", "latex_showcase_texonly", "html-pagesonly",
     ]
 end
 
@@ -261,7 +261,7 @@ function html_doc(
         build_directory, mathengine;
         htmlkwargs = (;),
         image_assets = ("images/logo.png", "images/logo.jpg", "images/logo.gif"),
-        warnonly = true,
+        warnonly = (VERSION.major == 1 && VERSION.minor <= 10),
         kwargs...
     )
     return @quietly withassets(image_assets...) do
@@ -727,7 +727,7 @@ end
 
 examples_latex_texonly_doc = if "latex_texonly" in EXAMPLE_BUILDS
     @info("Building mock package docs: LaTeXWriter/latex_texonly")
-    @quietly makedocs(
+    makedocs(
         format = Documenter.LaTeX(platform = "none"),
         sitename = "Documenter LaTeX",
         root = examples_root,
@@ -773,6 +773,54 @@ else
     nothing
 end
 
+examples_latex_listings_texonly_doc = if "latex_listings_texonly" in EXAMPLE_BUILDS
+    @info("Building mock package docs: LaTeXWriter/latex_listings_texonly")
+    makedocs(
+        format = Documenter.LaTeX(platform = "none", code_listings = "listings"),
+        sitename = "Documenter LaTeX",
+        root = examples_root,
+        build = "builds/latex_listings_texonly",
+        pages = Any[
+            "General" => [
+                "index.md",
+                "latex.md",
+                "unicode.md",
+                hide("hidden.md"),
+                "example-output.md",
+                "linenumbers.md",
+            ],
+            # SVG images nor code blocks in footnotes are allowed in LaTeX
+            # "Manual" => [
+            #     "man/tutorial.md",
+            #     "man/style.md",
+            # ],
+            hide(
+                "Hidden Pages" => "hidden/index.md", Any[
+                    "Page X" => "hidden/x.md",
+                    "hidden/y.md",
+                    "hidden/z.md",
+                ]
+            ),
+            "Library" => [
+                "lib/functions.md",
+                "lib/autodocs.md",
+            ],
+            "Expandorder" => [
+                "expandorder/00.md",
+                "expandorder/01.md",
+                "expandorder/AA.md",
+            ],
+        ],
+        doctest = false,
+        debug = true,
+        warnonly = [:footnote, :cross_references, :example_block, :eval_block],
+    )
+else
+    @info "Skipping build: LaTeXWriter/latex_listings_texonly"
+    @debug "Controlling variables:" EXAMPLE_BUILDS get(ENV, "DOCUMENTER_TEST_EXAMPLES", nothing)
+    nothing
+end
+
 examples_latex_simple_texonly_doc = if "latex_simple_texonly" in EXAMPLE_BUILDS
     @info("Building mock package docs: LaTeXWriter/latex_simple_texonly")
     @quietly makedocs(
@@ -849,6 +897,26 @@ else
     nothing
 end
 
+examples_latex_showcase_doc = if "latex_showcase_listings" in EXAMPLE_BUILDS
+    @info("Building mock package docs: LaTeXWriter/latex_showcase_listings")
+    @quietly makedocs(
+        format = Documenter.LaTeX(platform = "docker", version = v"1.2.3", code_listings = "listings"),
+        sitename = "Documenter LaTeX Showcase",
+        root = examples_root,
+        build = "builds/latex_showcase_listingslatex_showcase",
+        source = "src.latex_showcase",
+        pages = ["Showcase" => ["showcase.md", "docstrings.md"]],
+        remotes = Dict(@__DIR__() => (TestRemote(), "6ef16754bc5da93f67a4323fb204c5bd3e64f336")),
+        doctest = false,
+        debug = true,
+        warnonly = [:docs_block, :cross_references],
+    )
+else
+    @info "Skipping build: LaTeXWriter/latex_showcase"
+    @debug "Controlling variables:" EXAMPLE_BUILDS get(ENV, "DOCUMENTER_TEST_EXAMPLES", nothing)
+    nothing
+end
+
 examples_latex_showcase_texonly_doc = if "latex_showcase_texonly" in EXAMPLE_BUILDS
     @info("Building mock package docs: LaTeXWriter/latex_showcase_texonly")
     @quietly makedocs(

test/examples/pages/a.jl

@@ -3,9 +3,9 @@
 
 Links:
 
-- [`ccall`](@ref)
+- [`deepcopy`](@ref)
 - [`while`](@ref)
-- [`@time(x)`](@ref)
+- [`@eval(x)`](@ref)
 - [`T(x)`](@ref)
 - [`T(x, y)`](@ref)
 - [`f(::Integer)`](@ref)

test/examples/pages/b.jl

@@ -3,9 +3,9 @@
 
 Links:
 
-- [`ccall`](@ref)
+- [`deepcopy`](@ref)
 - [`while`](@ref)
-- [`@time`](@ref)
+- [`@eval`](@ref)
 - [`T`](@ref)
 - [`f`](@ref)
 - [`f(::Any)`](@ref)

test/examples/pages/c.jl

@@ -3,9 +3,9 @@
 
 Links:
 
-- [`ccall`](@ref)
+- [`deepcopy`](@ref)
 - [`while`](@ref)
-- [`@time`](@ref)
+- [`@eval`](@ref)
 - [`T`](@ref)
 - [`f`](@ref)
 - [`f(::Any)`](@ref)

test/examples/pages/d.jl

@@ -3,9 +3,9 @@
 
 Links:
 
-- [`ccall`](@ref)
+- [`deepcopy`](@ref)
 - [`while`](@ref)
-- [`@time`](@ref)
+- [`@eval`](@ref)
 - [`T`](@ref)
 - [`f`](@ref)
 - [`f(x)`](@ref)
@@ -21,9 +21,9 @@ mutable struct T end
 
 Links:
 
-- [`ccall`](@ref)
+- [`deepcopy`](@ref)
 - [`while`](@ref)
-- [`@time`](@ref)
+- [`@eval`](@ref)
 - [`T(x)`](@ref)
 - [`T(x, y)`](@ref)
 - [`T(x, y, z)`](@ref)
@@ -40,9 +40,9 @@ T(x) = T()
 
 Links:
 
-- [`ccall`](@ref)
+- [`deepcopy`](@ref)
 - [`while`](@ref)
-- [`@time`](@ref)
+- [`@eval`](@ref)
 - [`T()`](@ref)
 - [`T(x)`](@ref)
 - [`T(x, y)`](@ref)