在构建文档 PDF 时使用 Sphinx LaTeXBuilder 忽略 LaTeX 错误

Question

在我的项目中，我正在使用 Sphinx 的 LaTeXBuilder 构建文档的 PDF 版本，其中有几个文件和扩展名可能会导致输出问题。该项目托管在 Read the Docs 上，无法构建 PDF，并显示以下错误日志：

! LaTeX Error: Too deeply nested.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.8916 \begin{itemize}

这是

.tex

文件中对应的列表

\begin{itemize}
\item {} 
\sphinxAtStartPar
”current” (default) : the current is explicity supplied

\item {} 
\sphinxAtStartPar
”voltage”/”power”/”resistance” : solve an algebraic equation for                     current such that voltage/power/resistance is correct

\item {} 
\sphinxAtStartPar
”differential power”/”differential resistance” : solve a                     differential equation for the power or resistance

\item {} 
\sphinxAtStartPar
”CCCV”: a special implementation of the common constant\sphinxhyphen{}current                     constant\sphinxhyphen{}voltage charging protocol, via an ODE for the current

\item {} 
\sphinxAtStartPar
callable : if a callable is given as this option, the function                     defines the residual of an algebraic equation. The applied current                     will be solved for such that the algebraic constraint is satisfied.

\end{itemize}

\end{description}

\end{itemize}

这会导致嵌套列表，因此无法处理超过四个嵌套，据我所知。

我正在使用以下命令在强制模式下运行

latexmk

：

latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=myproject -interaction=nonstopmode

以避免这个问题。这会根据需要正确构建我的 PDF 文档，并忽略所有其他 LaTeX 警告，但由于 LaTeX 错误，程序仍然以错误代码 1 结束，这使我的工作流程失败。有没有办法忽略此错误并且不返回非零错误代码，也许可以通过

conf.py

内 LaTeX 输出的选项或配置值，因为 PDF 正在工作并且可以毫无问题地打开？就我而言，最好使用 Sphinx 本身解决问题，而不是在阅读文档时使用自定义构建命令。

输出最后的

Latexmk

错误日志是

Output written on myproject.pdf (195 pages, 781197 bytes).
Transcript written on myproject.log.
Latexmk: Getting log file 'myproject.log'
Latexmk: Examining 'myproject.fls'
Latexmk: Examining 'myproject.log'
Latexmk: Index file 'myproject.idx' was written
Latexmk: Missing input file 'myproject.toc' (or dependence on it) from following:
  No file myproject.toc.
Latexmk: Missing input file 'myproject.ind' (or dependence on it) from following:
  No file myproject.ind.
Latexmk: References changed.
Latexmk: References changed.
Latexmk: Log file says output to 'myproject.pdf'
Latexmk: Errors, so I did not complete making targets
Collected error summary (may duplicate other messages):
  pdflatex: Command for 'pdflatex' gave return code 1
      Refer to 'myproject.log' and/or above output for details

Latexmk: If appropriate, the -f option can be used to get latexmk
  to try to force complete processing.
make: *** [myproject.pdf] Error 12

这没有意义，因为我已经在使用

-f

命令行标志。或者，如果有办法提供构建的

myproject.PDF

文件来阅读文档（可能通过 https://docs.readthedocs.io/en/stable/build-customization.html#where-to-put-文件）即使是通过构建命令，它也会解决我的问题。

Answer 1

您可以使用

formats

配置键禁用“阅读文档”时自动生成 PDF（请参阅 https://docs.readthedocs.io/en/stable/config-file/v2.html#formats）

之后，您可以使用

build.jobs

配置键（https://docs.readthedocs.io/en/stable/config-file/v2.html#build-jobs）根据需要构建PDF并保存最终 PDF 文件位于

$READTHEDOCS_OUTPUT/pdf

目录下。这是一个例子：

version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.11"
  jobs:
    post_build:
      # Create the directory where to put the files
      - mkdir --parents $READTHEDOCS_OUTPUT/pdf
      # Generate the PDF here as you want
      # and copy the resulting PDF file to the correct path
      - cp "<your-pdf-file>.pdf" $READTHEDOCS_OUTPUT/pdf/$READTHEDOCS_PROJECT.pdf


# Disable PDF format
formats: []