ci: 修复 PDF 构建 (#143)

* doc.build: 更新 LaTeXWriter.jl 的原始版本

* doc.build: 更换 tex 后端，使用自定义 docker

* ci: 使用 docker 构建 PDF

.github/workflows/pdf.yml

@@ -18,12 +18,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Build and deploy
-        timeout-minutes: 90
-        uses: JuliaCN/[email protected]
+      - uses: julia-actions/setup-julia@v2
         with:
-          project_dir: 'doc'
-          format: pdf # trigger the pdf compilation in our doc/make.jl
+          version: '1.10'
+          show-versioninfo: true
+      - name: Install dependencies
+        shell: julia --project=doc --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+      - name: Build PDF
+        run: julia --project=doc/ doc/make.jl pdf texplatform=docker
       - name: upload complied PDF file
         uses: actions/upload-artifact@v4
         with:

contrib/LaTeXWriter.jl

@@ -1,54 +1,87 @@
-using DocumenterLaTeX, Markdown
-import Documenter: Documents, Documenter, Writers, Utilities
-import Documenter.Writers.LaTeXWriter: piperun, _print
+using Markdown
+import Documenter.LaTeXWriter.MarkdownAST: MarkdownAST, Node
+import Documenter.LaTeXWriter: latex, compile_tex
+import Documenter.LaTeXWriter:
+    Context, Node, LaTeX,
+    piperun, _print
 
 const LaTeX_CC="xelatex"
+# 默认 juliadocs/documenter-latex
 const DOCKER_IMAGE = "tianjun2018/documenter-latex:latest"
 
-function Documenter.Writers.LaTeXWriter.latexinline(io, math::Markdown.LaTeX)
+"""
+https://github.com/JuliaDocs/Documenter.jl/blob/v1.8.0/src/latex/LaTeXWriter.jl#L832
+"""
+function latex(io::Context, node::Node, math::MarkdownAST.InlineMath)
     # Handle MathJax and TeX inconsistency since the first wants `\LaTeX` wrapped
     # in math delims, whereas actual TeX fails when that is done.
-    math.formula == "\\LaTeX" ? _print(io, " ", math.formula, " ") : _print(io, " \\(", math.formula, "\\) ")
+    # XXX: 这里确保 math.math 前后都有空格
+    math.math == "\\LaTeX" ? _print(io, " ", math.math, " ") : _print(io, "\\(", math.math, "\\)")
+    return
 end
 
-function Documenter.Writers.LaTeXWriter.compile_tex(doc::Documents.Document, settings::LaTeX, texfile::String)
+"""
+# XXX1: 改用 LaTeX_CC 作为后端
+# XXX2: 使用自定义的 docker 镜像
+
+https://github.com/JuliaDocs/Documenter.jl/blob/v1.8.0/src/latex/LaTeXWriter.jl#L179-L234
+"""
+function compile_tex(doc::Documenter.Document, settings::LaTeX, fileprefix::String)
     if settings.platform == "native"
         Sys.which("latexmk") === nothing && (@error "LaTeXWriter: latexmk command not found."; return false)
         @info "LaTeXWriter: using latexmk to compile tex."
-        piperun(`latexmk -f -interaction=nonstopmode -view=none -$(LaTeX_CC) -shell-escape $texfile`)
-        return true
-
-        # NOTE: 中文排版依然有问题，我们暂时不管他们。输出的pdf大部分情况下依然可以使用。
-        # try
-        #     piperun(`latexmk -f -interaction=nonstopmode -view=none -$(LaTeX_CC) -shell-escape $texfile`)
-        #     return true
-        # catch err
-        #     logs = cp(pwd(), mktempdir(); force=true)
-        #     @error "LaTeXWriter: failed to compile tex with latexmk. " *
-        #            "Logs and partial output can be found in $(Utilities.locrepr(logs))." exception = err
-        #     return false
-        # end
+        try
+            # XXX1
+            piperun(`latexmk -f -interaction=batchmode -halt-on-error -view=none -$(LaTeX_CC) -shell-escape $(fileprefix).tex`, clearlogs = true)
+            return true
+        catch err
+            logs = cp(pwd(), mktempdir(; cleanup = false); force = true)
+            @error "LaTeXWriter: failed to compile tex with latexmk. " *
+                "Logs and partial output can be found in $(Documenter.locrepr(logs))" exception = err
+            return false
+        end
+    elseif settings.platform == "tectonic"
+        @info "LaTeXWriter: using tectonic to compile tex."
+        tectonic = isnothing(settings.tectonic) ? Sys.which("tectonic") : settings.tectonic
+        isnothing(tectonic) && (@error "LaTeXWriter: tectonic command not found."; return false)
+        try
+            piperun(`$(tectonic) -X compile --keep-logs -Z shell-escape $(fileprefix).tex`, clearlogs = true)
+            return true
+        catch err
+            logs = cp(pwd(), mktempdir(; cleanup = false); force = true)
+            @error "LaTeXWriter: failed to compile tex with tectonic. " *
+                "Logs and partial output can be found in $(Documenter.locrepr(logs))" exception = err
+            return false
+        end
     elseif settings.platform == "docker"
         Sys.which("docker") === nothing && (@error "LaTeXWriter: docker command not found."; return false)
         @info "LaTeXWriter: using docker to compile tex."
+        # XXX1
         script = """
-            mkdir /home/zeptodoctor/build
-            cd /home/zeptodoctor/build
-            cp -r /mnt/. .
-            latexmk -f -interaction=nonstopmode -view=none -$(LaTeX_CC) -shell-escape $texfile
-            """
+        mkdir /home/zeptodoctor/build
+        cd /home/zeptodoctor/build
+        cp -r /mnt/. .
+        latexmk -f -interaction=batchmode -halt-on-error -view=none -$(LaTeX_CC) -shell-escape $(fileprefix).tex
+        """
         try
-            piperun(`docker run -itd -u zeptodoctor --name latex-container -v $(pwd()):/mnt/ --rm $(DOCKER_IMAGE)`)
+            # XXX2: 使用自定义的 docker 镜像
+            piperun(`docker run -itd -u zeptodoctor --name latex-container -v $(pwd()):/mnt/ --rm $(DOCKER_IMAGE)`, clearlogs = true)
             piperun(`docker exec -u zeptodoctor latex-container bash -c $(script)`)
-            piperun(`docker cp latex-container:/home/zeptodoctor/build/. .`)
+            piperun(`docker cp latex-container:/home/zeptodoctor/build/$(fileprefix).pdf .`)
             return true
         catch err
-            logs = cp(pwd(), mktempdir(); force=true)
+            logs = cp(pwd(), mktempdir(; cleanup = false); force = true)
             @error "LaTeXWriter: failed to compile tex with docker. " *
-                   "Logs and partial output can be found in $(Utilities.locrepr(logs))." exception = err
+                "Logs and partial output can be found in $(Documenter.locrepr(logs))" exception = err
             return false
         finally
-            try; piperun(`docker stop latex-container`); catch; end
+            try
+                piperun(`docker stop latex-container`)
+            catch
+            end
         end
+    elseif settings.platform == "none"
+        @info "Skipping compiling tex file."
+        return true
     end
 end

doc/make.jl

@@ -11,7 +11,7 @@ Pkg.instantiate()
 using Documenter
 using DocumenterInventoryWritingBackport
 include("../contrib/HTMLWriter.jl")
-# include("../contrib/LaTeXWriter.jl")
+include("../contrib/LaTeXWriter.jl")
 
 
 # Documenter Setup.