From 071e79fb33e8051a6a2d901f57615881dc12a0e8 Mon Sep 17 00:00:00 2001 From: Chengyu Han Date: Sun, 22 Dec 2024 20:34:39 +0800 Subject: [PATCH] =?UTF-8?q?ci:=20=E4=BF=AE=E5=A4=8D=20PDF=20=E6=9E=84?= =?UTF-8?q?=E5=BB=BA=20(#143)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc.build: 更新 LaTeXWriter.jl 的原始版本 * doc.build: 更换 tex 后端，使用自定义 docker * ci: 使用 docker 构建 PDF --- .github/workflows/pdf.yml | 16 ++++--- contrib/LaTeXWriter.jl | 91 ++++++++++++++++++++++++++------------- doc/make.jl | 2 +- 3 files changed, 74 insertions(+), 35 deletions(-) diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index 5e1beaf1..c71b0d58 100644 --- a/.github/workflows/pdf.yml +++ b/.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/documenter-latex-action@v0.1.0 + - 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: diff --git a/contrib/LaTeXWriter.jl b/contrib/LaTeXWriter.jl index 32402775..8f07f006 100644 --- a/contrib/LaTeXWriter.jl +++ b/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 diff --git a/doc/make.jl b/doc/make.jl index e37c9255..da834537 100644 --- a/doc/make.jl +++ b/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.