In my project, I am building a PDF version of my documentation with Sphinx's LaTeXBuilder where I have several files and extensions that can potentially cause problems with the output. The project is hosted on Read the Docs, which fails to build a PDF with this error log:
! LaTeX Error: Too deeply nested.
See the LaTeX manual or LaTeX Companion for explanation.
Type H <return> for immediate help.
...
l.8916 \begin{itemize}
and this is the corresponding list in the .tex file
\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}
which is causing a nested list and as such cannot be handled for more than four nestings as I have been made aware.
I am running latexmk in force mode with this command:
latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=myproject -interaction=nonstopmode
to avoid the issue. This builds my PDF documentation correctly as required and ignores all other LaTeX warnings, but the program still ends with an error code 1 due to the LaTeX error, which fails the workflow for me. Is there a way to ignore this error and not return a non-zero error code, perhaps through the options or configuration values for LaTeX output inside conf.py, because the PDF is working and can be opened without issues? In my case it would be better to solve the problem with Sphinx itself, rather than using a custom build command on Read the Docs.
The Latexmk error log at the end of the output is
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
which does not make sense, because I am already using the -f command-line flag. Alternatively, if there is a way to provide the built myproject.PDF file to Read the Docs (might be through https://docs.readthedocs.io/en/stable/build-customization.html#where-to-put-files) even if it is through a build command, it would fix my issue.
You can disable the auto-generation of PDF on Read the Docs by using the formats configuration key (see https://docs.readthedocs.io/en/stable/config-file/v2.html#formats)
After that, you can build the PDF as you want using build.jobs configuration key (https://docs.readthedocs.io/en/stable/config-file/v2.html#build-jobs) and saving the final PDF file under $READTHEDOCS_OUTPUT/pdf directory. Here an example:
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: []