Traditional vanilla LaTeX style

[yves-chevallier]

I would like to convert my Sphinx documentation into traditional LaTeX book. This is really painful because Sphinx redefines almost everything and does it by small hacks everywhere.

For example if I simply want to use \fancyhdr with a \frontmatter section. I have to redefine \sphinxtableofcontents to remove the small hacks that change the page numbering:

\makeatletter
\renewcommand{\sphinxtableofcontents}{%
  %\pagenumbering{roman}% <-- Not wanted
  \begingroup
    \parskip \z@skip
    \sphinxtableofcontentshook
    \tableofcontents
  \endgroup
  % before resetting page counter, let's do the right thing.
  \if@openright\cleardoublepage\else\clearpage\fi
  %\pagenumbering{arabic}% <-- Not wanted
}
\makeatother

To get normal sections styles I have to copy sphinx.sty locally in my _templates and remove the following to get rid of the (ugly) \Large that shouldn't be there, or at list be configurable otherwise :

% Augment the sectioning commands used to get our own font family in place,
% and reset some internal data items (\titleformat from titlesec package)
\titleformat{\section}{\Large\py@HeaderFamily}%
            {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsection}{\large\py@HeaderFamily}%
            {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsubsection}{\py@HeaderFamily}%
            {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
% By default paragraphs (and subsubsections) will not be numbered because
% sphinxmanual.cls and sphinxhowto.cls set secnumdepth to 2
\titleformat{\paragraph}{\py@HeaderFamily}%
            {\py@TitleColor\theparagraph}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subparagraph}{\py@HeaderFamily}%
            {\py@TitleColor\thesubparagraph}{0.5em}{\py@TitleColor}{\py@NormalColor}

The headers and footers have also to be redefined to remove the unwanted \py@HeaderFamily\nouppercase.

IMHO generating LaTeX is to get beautful LaTeX documents otherwise it doesn't worth it.

Instead of spending a lot of time reverting what Sphinx does on LaTeX I suggest a feature/option/command to use vanilla LaTeX templates which can be either : article or book.

[mgeier]

I'm not sure if that's better, but I've done it the other way round:

I've only generated the "body" with this minimal latex.tex_t template:

<%= body %>
<%= atendofbody %>

I'm then using \input{...} to include the file generated by Sphinx into my hand-written "vanilla" LaTeX file.

The downside is that I have to manually add some stuff from the original Sphinx-generated file to my main preamble to make it compile again.

It may not make a difference in your case, but I thought I'd mention it anyway ...

[tk0miya]

Current LaTeX builder is designed to control styles via Sphinx configurations. So it is not a vanilla LaTeX. So it would be nice if you make another vanilla LaTeX builder!

[yves-chevallier]

@tk0miya That would be indeed a much cleaner solution to have another builder.

[jfbu]

@yves-chevallier I have been refactoring the latex style files (did not touch the class files sphinxmanual and sphinxhowto) at #8790 (which follows up #8769 already merged in master branch). It will be easier then to control some things like the one you mentioned with titlesec or fancyhdr. (à propos \titleformat I fixed an invisible long-standing bug by the way at #8789).

There are things for which only real customization possible is via the text styling macros. I am thinking in particular of the code for tables or code-blocks. Particularly for tables we achieve things for which there is no solution in LaTeX world: for example have a multirow multicolumn multiparagraphs cell containing footnotes and code-blocks in a table. There isn't a single LaTeX package existing which can achieve that. The solution is via a tight cooperation between the latex writer which outputs the mark-up and the custom latex macros and also the latex table templates. Many things though such as vertical spacing, or the text style in the table header row are available via latex commands with public names that you can redefine. And you can use your own table templates. But you will always need the code that #8790 now has gathered into sphinxlatextables.sty (part of it was in sphinx.sty so far, and the rest in sphinxmulticell.sty).

To a lesser extent, the handling of code-blocks also needs a heavy load of custom macros, this was needed to handle continuation hints at a pagebreak and to implement codeline wrapping. Solutions in LaTeX world are not applicable to us, for example the minted package, which basically has the same structure as us of using fancyvrb for LaTeX aspect and Pygmentize for highlighting. Its codeline wrapping suffers same limitations as ours (see #8686).

Many more aspects of Sphinx latex output are currently customizable than it was the case in the past (see for example the chapter LaTeX customization, in the PDF version of our docs, in particular colours and dimensions related to various framed boxes, the ones for code-blocks, the ones for admonitions and warnings) and now with smaller separate pieces, some things will be controllable by a wholesale replacement of files: for example not using titlesec will be as easy as overwrite the file sphinxlatexstyleheadings.sty. But as I said, many advices and packages you will find on LaTeX forums will not be valid solution to us. For example, we basically can't let figures float because there is simply no LaTeX solution which is fully automatic, and many projects will end up with pictures going the wrong place and strange vertical blanks in text (from wrapfig package which we have to use very cautiously). Most of LaTeX in fact requires often manual intervention to fix problems.

There is no vanilla LaTeX, but only sophisticated LaTeX which can achieve the translation from our possible variety of input into LaTeX output.