8

We are exploring the features of Sphinx in order to rebuild our legacy manuals. We already ported most of the former manual to Sphinx. Now I'm exploring the possibilities to adapt our company styles.

Especially, we would like to change the appearance of the headers and footers in the PDF manual. Including a company logo and changing the appearance of even and odd pages.

Hence, I included the following preamble in my conf.py with a custom pagestyle using the package fancyhdr.

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

Unfortunately, the headers only changes before begin{document}, afterwards the Sphinx Style File sphinx.sty overwrites somehow my settings.

The following snippet from sphinx.sty might cause the issue: 

% 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}
  }
}

What might be a possible workaround?

Aleph0
  • 5,816
  • 4
  • 29
  • 80

1 Answers1

8

The table of contents code (in sphinxmanual.cls) ends up with 

\ifdefined\fancyhf\pagestyle{normal}\fi

The comment in sphinx.sty says:

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

Thus the simplest should be for your conf.py setting to overwrite the \fancypagestyle{normal}, just re-issue it to your liking.

You will need to wrap the whole latex in \makeatletter...\makeatother if you use \py@HeaderFamily. And use Python raw strings to avoid having to double all backslashes.

in details, here I copy the original definition to conf.py so that it can be customized from there

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
""",
}