使用 Sphinx 在 Latex 中自定义 headers 和页脚

Question

我们正在探索 Sphinx 的功能，以重建我们的遗留手册。我们已经将大部分以前的手册移植到 Sphinx。现在我正在探索调整我们公司风格的可能性。

特别是，我们想更改 PDF 手册中 headers 和页脚的外观。包括公司徽标并更改偶数页和奇数页的外观。

因此，我在我的 conf.py 中包含了以下序言和使用包 fancyhdr.

的自定义页面样式

latex_elements = {
    'preamble' : '''\
        \pagestyle{fancy}
        \fancyhf{}
        \fancyhead[LE,RO]{My Header}'''
}

不幸的是，headers 仅在 begin{document} 之前更改，之后 Sphinx 样式文件 sphinx.sty 以某种方式覆盖了我的设置。

来自 sphinx.sty 的以下代码片段可能会导致此问题：

% Redefine the 'normal' header/footer style when using "fancyhdr" package:
\spx@ifundefined{fancyhf}{}{
  % Use \pagestyle{normal} as the primary pagestyle for text.
  \fancypagestyle{normal}{
    \fancyhf{}
    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
    \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
    \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
    \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}}
    \renewcommand{\headrulewidth}{0.4pt}
    \renewcommand{\footrulewidth}{0.4pt}
    % define chaptermark with \@chappos when \@chappos is available for Japanese
    \spx@ifundefined{@chappos}{}
      {\def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}}
  }
  % Update the plain style so we get the page number & footer line,
  % but not a chapter or section title.  This is to keep the first
  % page of a chapter and the blank page between chapters `clean.'
  \fancypagestyle{plain}{
    \fancyhf{}
    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
    \renewcommand{\headrulewidth}{0pt}
    \renewcommand{\footrulewidth}{0.4pt}
  }
}

可能的解决方法是什么？

Answer 1

内容代码的 table（在 sphinxmanual.cls 中）以

结尾

\ifdefined\fancyhf\pagestyle{normal}\fi

sphinx.sty中的评论说：

  % Use \pagestyle{normal} as the primary pagestyle for text.

因此，最简单的应该是您的 conf.py 设置覆盖 \fancypagestyle{normal}，只需根据您的喜好重新发布即可。

如果使用 \py@HeaderFamily，则需要将整个乳胶包裹在 \makeatletter...\makeatother 中。并使用 Python 原始字符串以避免必须将所有反斜杠加倍。

详细的，这里我把原来的定义复制到conf.py，这样就可以从那里自定义了

latex_elements = {
  'preamble': """
\makeatletter
  \fancypagestyle{normal}{
    \fancyhf{}
    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
    \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
    \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
    \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}}
    \renewcommand{\headrulewidth}{0.4pt}
    \renewcommand{\footrulewidth}{0.4pt}
    % define chaptermark with \@chappos when \@chappos is available for Japanese
    \spx@ifundefined{@chappos}{}
      {\def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}}
  }
\makeatother
""",
}

使用 Sphinx 在 Latex 中自定义 headers 和页脚

Customize headers and footers in Latex using Sphinx

latex

tex

pdflatex

python-sphinx