使用Sphinx自定义LaTeX样式生成PDF时RST内容缺失空白问题

问题根源 #

你自定义的main.sty文件错误包含了完整LaTeX文档的\begin{document}和\end{document}标记。Sphinx生成PDF的流程是先自动拼接完整的.tex文件，在预导言区加载你指定的样式，之后自动插入RST转换得到的LaTeX内容，最后生成\end{document}收尾。你在sty文件里提前闭合了document环境，所有RST对应的内容都会被识别为文档外的无效内容，自然不会渲染，只显示了你写在sty里的背景样式。

修复方案 #

第一步：调整main.sty文件定位，剥离文档内容 #

sty文件是纯样式配置文件，只能放预导言区命令，删掉所有和文档内容相关的结构和元素。修改后的main.sty参考：

\PassOptionsToPackage{english}{babel}
\usepackage{amsmath}
\usepackage{color,pxfonts,fix-cm}
\usepackage{latexsym}
\usepackage[mathletters]{ucs}
\DeclareUnicodeCharacter{32}{$\ $}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{pict2e}
\usepackage{wasysym}
\usepackage{tikz}
\pagestyle{empty}
\geometry{left=0.2in, top=0.5in, paperwidth=595pt, paperheight=878pt}
% 预定义颜色
\definecolor{color_93343}{rgb}{0.25098,0.25098,0.25098}
\definecolor{color_217206}{rgb}{0.737255,0.839216,0.443137}

第二步：将自定义背景、固定元素插入Sphinx渲染钩子 #

你之前写的背景图、固定占位文本，通过全局背景钩子插入到所有页面，修改conf.py里的latex_elements配置：

latex_engine = 'pdflatex'

latex_additional_files = [
    'latexImage_ab7aceb12f4add82da5ce423202fd278.png',
    'main.sty'
]

latex_elements = {
    'extraclassoptions': 'openany',
    'preamble' : r"""
        \usepackage{main}
        \renewcommand{\subtitle}{%s}
        % 加载全局背景工具
        \usepackage{eso-pic}
        % 所有页面添加背景层
        \AddToShipoutPictureBG{%
            \begin{picture}(-5,0)(2.5,0)
            \put(-15,-837.4999){\includegraphics[width=596.25pt,height=887.25pt]{latexImage_ab7aceb12f4add82da5ce423202fd278.png}}
            \put(55.775,-99.78003){\fontsize{11}{1}\usefont{T1}{cmr}{m}{n}\selectfont\color{color_93343} }
            \put(55.525,-810){\fontsize{11}{1}\usefont{T1}{cmr}{m}{n}\selectfont\color{color_93343} }
            \put(282.38,-810){\fontsize{11}{1}\usefont{T1}{cmr}{m}{n}\selectfont\color{color_93343} }
            \put(509.48,-810){\fontsize{11}{1}\usefont{T1}{cmr}{m}{n}\selectfont\color{color_93343} }
            \put(55.775,-823.5){\fontsize{11}{1}\usefont{T1}{cmr}{m}{n}\selectfont\color{color_93343} }
            \put(55.775,-118.05){\fontsize{16}{1}\usefont{T1}{cmr}{b}{n}\selectfont\color{color_217206} }
            \put(55.775,-150.3){\fontsize{16}{1}\usefont{T1}{cmr}{b}{n}\selectfont\color{color_217206} }
            \end{picture}
        }
    """ % (project)
}

如果只需要首页显示该背景，把\AddToShipoutPictureBG改成带星号的\AddToShipoutPictureBG*即可。

第三步：验证RST索引配置 #

确认你项目根目录的index.rst中toctree指令正确包含了所有需要生成的RST文件，无特殊需求不需要手动配置latex_documents参数，Sphinx会默认按toctree结构生成内容。

内容的提问来源于stack exchange，提问作者Chippa29