How to make LaTeX and PDF generation in Sphinx

  • Tutorial
When we introduced the Sphinx documentation generator at home a year and a half ago , we were faced with the task of generating PDF. The case was very difficult. There were no ready-made “take and do” instructions on the resources. We went by trial and error. After 3 days of torment, we were able to generate PDF with the design we needed.

Done and forgot - it works the same. Until a problem with fonts happened. They suffered again and decided again. But what is remarkable - since then, ready-made instructions for generating PDFs have not appeared on the Internet. Therefore, I spread our. Inside is an algorithm with comments and template files, features of ReST for LaTeX, which we have collected empirically.



This article is for those who already use Sphinx, but have problems with LaTeX or PDF. If you are only considering Sphinx as a documentation tool, it will be helpful to present how to prepare and submit documentation in these formats.

I must say right away why ReadTheDocs, where PDF generation is already provided, did not suit us:

  1. Our documentation must be hosted on an internal network.
  2. You need to be able to upload to PDF only part of the documentation (folder)
  3. Generation should go through LaTeX, the template of which, in turn, we wanted to change for different tasks and for corporate style

Why LaTeX


For the simplest PDF, rst2pdf is fine . But the simplest PDF is not suitable for us, because we need to do it in beauty, use stylized templates. Therefore, we use LaTeX as an intermediate format.

It allows you to solve a lot of issues with pagination, table of contents, typography, word wrap, footnotes, tables, cross-references, illustrations, etc. The document structure in LaTeX can be individually styled, the same data structure can be displayed in different formats, with different design. It is driven by LaTeX styles.



We need stylized PDFs to generate output documentation for the client: user instructions, reports, commercial offers, simple presentations.

Let's get started


Thanks to Andrei Bezrukov ( @aur ), who collected the initial information and checked the basic things.

1. Preparation


Python and Sphinx should already be on the server (we have Debian), documentation has been prepared in reStructuredText, the generation of which has been verified in html format.

We put packages for LaTeX. Example:

sudo apt-get install  texmaker gummi texlive texlive-full texlive-latex-recommended latexdraw intltool-debian lacheck libgtksourceview2.0-0 libgtksourceview2.0-common lmodern luatex po-debconf tex-common texlive-binaries texlive-extra-utils texlive-latex-base texlive-latex-base-doc texlive-luatex texlive-xetex texlive-lang-cyrillic texlive-fonts-extra texlive-science texlive-latex-extra texlive-pstricks

In the conf.py documentation config, add / uncomment the latex_documents parameter :

# Grouping the document tree into LaTeX files. List of tuples# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
 ('index', 'yourdoc.tex', u'DocName', u'YourName', 'manual'),
]

Here are other basic settings for LaTeX: page size, font, preamble, etc.

2. LaTeX Generation


We execute the command:

sphinx-build -b latex doc/source/ doc/latex/

where source is the folder with the root index.rst file, and latex is the destination folder.

All documentation is generated immediately, not individual files. As a result, a bunch of files will appear in the root of the latex folder, among which the .tex file is the main documentation file in latex format. An example of the contents of a folder at this stage in the latex_default.zip archive .

How to generate in PDF only a part of the documentation (folder)
We have found such a way out. We make a copy of the necessary part with the script, add conf.py to it, i.e. we make the piece of documentation a separate documentation. Otherwise, the generation will fail.

3. Changes to latex (.tex file)


If you need to change the basic layout of LaTeX, and the basic settings in conf.py are not enough, we change the document template itself, its layout and styles.

There is a preamble in the .tex file (up to \ begin {document}) where packages are connected, variables are defined, styles can be described, etc. Here we connect additional packages that we need.

Examples

To support speakers
\usepackage{multicol}

Using vector graphics (drawing shapes, filling the page background, etc.)
\usepackage{tikz}

Landscape orientation
\usepackage[screen,margin=0.8in]{geometry}

Presentation Type
\usepackage{geometry}
\geometry{landscape}

The .tex file contains the \ maketitle directive , which creates a standard cover page using information about the document name (\ title), author (\ author) and the date the text was written (\ date).

We can replace \ maketitle with our own template. We created a separate file TitlePage.tex for ourselves - a template for the main page, to which we replace \ maketitle. For different documents we use different design templates.

Examples

Table of contents (toc)
\tableofcontents
\phantomsection\label{index::doc}

Legal information and copyrights on the second page of the document
\noindent Copyright \copyright\ [COPYRIGHT]\\ 
\noindent \textsc{[COPYRIGHT_2]}\\ % Publisher
\noindent \textsc{\url{https://netoria.ru}}\\ % URL
\noindent [RIGHT_INFO] \\ % License information
\noindent \textit{Дата публикации: [DOC_DAY]}
\newpage
where [COPYRIGHT], [RIGHT_INFO], etc. are replaced with the desired content.

At the end of the .tex file, you can also add some kind of completion template. So we insert our logo and contacts, and sometimes an external PDF file of an advertising nature.

Example
\newpage
\textcolor{red}{\noindent\makebox[\linewidth]{\rule{\textwidth}{0.4pt}}}\par\vspace{0.5cm}
\begin{figure}[h]
\begin{center}
\begin{minipage}[h]{0.3\linewidth}
\includegraphics[width=0.8\linewidth]{logo_contact.png}
\end{minipage}
\hfill 
\begin{minipage}[h]{0.6\linewidth}
{ООО Нетория}\par{+7 (3452) 692-242}\par{netoria.ru}\par{info@netoria.ru}
\end{minipage}
\end{center}
\end{figure}
\par\vspace{0.5cm}
\textcolor{red}{\noindent\makebox[\linewidth]{\rule{\textwidth}{0.4pt}}}
\includepdf[pages={1,2}]{advertising.pdf}
\renewcommand{\indexname}{Алфавитный указатель}
\printindex
\end{document}

We copy our logo.png logo to the latex folder, because it is used in our cover page template.

4. Generation pdf


We perform the first generation of the PDF document with the command:

pdflatex yourdoc.tex

Files appear in the latex folder:

  • .aux - Cross Reference Information
  • .toc - table of contents file
  • .log - PDF generation log
  • .pdf - PDF file. But it still does not have a table of contents

We generate and style the table of contents with the command:

makeindex yourdoc.idx

We carry out repeated and final generation of PDF: 

pdflatex yourdoc.tex

The final PDF file appears in the same folder . An example of the contents of a folder at this stage in the latex_modified.zip archive .

If you do not do intermediate generations, then the output will be a document without a table of contents. The table of contents toctree the root file becomes the table of contents of the PDF book. The contents table of each file becomes the table of contents for each chapter. All table of contents links, internal and external ReST links are correctly transferred.

If there are errors in ReST (there are no images, incorrect syntax, etc.), then when generating PDF, the pdflatex command will also generate errors and wait for user actions (Enter - skip and continue, H - fix automatically, X - interrupt generation). To disable this interactive command, you need to call the command with a parameter that will terminate the process with the first error:

pdflatex -halt-on-error yourdoc.tex

ReST Requirements for LaTeX Generation


For the html version, these requirements are non-critical, documentation will still be generated. But for LaTeX, this is fatal. The list is compiled empirically.

  1. There must physically exist pictures that are used in the text.
  2. By default, the maximum nesting of bulleted and numbered lists is 3. If there is more, there will be an error (“LaTeX Error: Too deeply nested”). It is solved this way , verified.
  3. Listings (source code): put hyphens for long lines, this will not happen automatically. Otherwise, the lines will go beyond the limits of the page, will be “cut off”.
  4. When copying text from somewhere, delete special characters, if any (emoticons, html special characters).
  5. It is better that there are no ReST syntax errors.

Also, sometimes pages are broken inappropriately if there are pictures, tables, warning blocks. Then in the rst file you have to set the page break for latex:

.. raw:: latex 
	\newpage

Font problem


If a problem occurs, first of all, look at the logs - the reasons may be different. We had 2 situations. Add yours in the comments.

One fine day the generation stopped working. Associated with the server update. We looked at the logs - sphinx began to look for fonts in another folder. We decided through the mount font folders, prescribed it in the startup of the server.

Another case. LaTeX needs tfm fonts. When installing fonts on the server, they should be generated automatically. For some reason, this does not always work. We solved this by manually starting the generation ( mktextfm <font name> command ) for such fonts.

Download for free and without sms



I hope this helps you to save several hours or days when solving a similar problem.
Please report errors in PM.
Tags:

Also popular now: