How to generate LaTeX and PDF in Sphinx
When we introduced the documentation generator Sphinx a year and a half ago, we were faced with the task of generating a PDF. The case turned out to be very difficult. There were no ready-made instructions “take and do” on resources. We went by trial and error. After 3 days of torment, we knew how to generate PDF with the design we needed.
Made and forgotten - works the same. Until there was a problem with the fonts. Again we suffered and again decided. But what is remarkable - since the finished instructions for generating in PDF on the Internet has not appeared. Therefore, spread our. Inside, an algorithm with comments and template files, ReST features for LaTeX, which we collected empirically.
')
The 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’ll tell you right away why ReadTheDocs, where PDF generation is already provided, didn’t suit us:
For the simplest PDF, rst2pdf is suitable. But the simplest PDF is not suitable for us, because we need to make beauty, use stylized templates. Therefore, we use LaTeX, as an intermediate format.
It allows you to solve a lot of issues with page numbering, table of contents, typography, word wrap, footnotes, tables, cross-references, illustrations, etc. The structure of the document in LaTeX can be styled separately, the same data structure can be displayed in different formats, with different design. This is controlled by the LaTeX styles.
We need stylized PDFs to form the output documentation for the client: user instructions, reports, offers, simple presentations.
Thanks to Andrey Bezrukov ( @aur ), who collected the primary information and checked the basic things.
Python and Sphinx should already be on the server (we have Debian), the documentation has been prepared in reStructuredText, the generation of which is tested on the html format.
We put packages for LaTeX. Example:
In the conf.py documentation config, add / uncomment the latex_documents parameter:
Here are the other basic settings for LaTeX: page size, font, preamble, etc.
Execute the command:
where source is the folder with the root file index.rst, 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 file of documentation in the latex format. An example of the contents of the folder at this stage in the archive is latex_default.zip .
If you need to change the basic layout of LaTeX, and the basic settings in conf.py are not enough, change the document template itself, its layout and styles.
There is a preamble in the .tex file (before \ begin {document}), where packages are connected, variables are defined, styles can be described, etc. Here we include additional packages that we need.
Examples
The .tex file contains the \ maketitle directive, which creates a standard title page using information about the title of the document (\ title), the author (\ author), and the date the text was written (\ date).
We can replace the \ maketitle with your template. We have created for ourselves a separate file TitlePage.tex - the main page template, with which we replace \ maketitle. For different documents use different design templates.
Examples
At the end of the .tex-file, you can also add any template-completion. So we insert our logo and contacts, and sometimes an external advertising PDF file.
We copy our logo.png logo into the latex folder, since it is used in our title page template.
We perform the first generation of a PDF document with the command:
Files appear in the latex folder:
Perform the generation and styling of the table of contents with the command:
We perform repeated and final PDF generation:
The final PDF file appears in the same folder. An example of the contents of the folder at this stage in the archive is latex_modified.zip .
If you do not make intermediate generations, then the output will be a document without a table of contents. The contents of the toctree root file become the contents of the PDF book. The table of contents of each file becomes the table of contents of each chapter. All links to the table of contents, internal and external links ReST correctly transferred.
If there are errors in ReST (there are no images, incorrect syntax, and the like), then when generating PDF, the pdflatex command will also generate errors and wait for user actions (Enter - skip and continue, H - correct automatically, X - terminate generation). To disable this interactive command, call the command with a parameter that terminates the process at the first error:
For the html version, these requirements are non-critical, the documentation will still be formed. But for LaTeX it is fatal. List compiled by experience.
Also, sometimes the pages are broken inadequately, if there are pictures, tables, blocks of warnings. Then in the rst file you have to set a page break for latex:
If a problem occurs, first see the logs - the reasons may be different. We had 2 situations. Add your own in the comments.
One day, the generation stopped working. Tied it up with a server update. We looked at the logs - sphinx began to look for fonts in another folder. We decided through the mount of the folder of fonts, registered it in the server startup.
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 decided to do this by manually starting the generation ( mktextfm <font name> command) for such fonts.
I hope this helps you save a few hours or days when solving a similar problem.
Please report errors in lichku.
Made and forgotten - works the same. Until there was a problem with the fonts. Again we suffered and again decided. But what is remarkable - since the finished instructions for generating in PDF on the Internet has not appeared. Therefore, spread our. Inside, an algorithm with comments and template files, ReST features for LaTeX, which we collected empirically.
')
The 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’ll tell you right away why ReadTheDocs, where PDF generation is already provided, didn’t suit us:
- Our documentation should be posted on the internal network.
- You need to be able to upload only part of the documentation to the PDF (folder)
- 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 suitable. But the simplest PDF is not suitable for us, because we need to make beauty, use stylized templates. Therefore, we use LaTeX, as an intermediate format.
It allows you to solve a lot of issues with page numbering, table of contents, typography, word wrap, footnotes, tables, cross-references, illustrations, etc. The structure of the document in LaTeX can be styled separately, the same data structure can be displayed in different formats, with different design. This is controlled by the LaTeX styles.
We need stylized PDFs to form the output documentation for the client: user instructions, reports, offers, simple presentations.
Let's get started
Thanks to Andrey Bezrukov ( @aur ), who collected the primary information and checked the basic things.
1. Preparation
Python and Sphinx should already be on the server (we have Debian), the documentation has been prepared in reStructuredText, the generation of which is tested on the 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 the other basic settings for LaTeX: page size, font, preamble, etc.
2. Generation of LaTeX
Execute the command:
sphinx-build -b latex doc/source/ doc/latex/ where source is the folder with the root file index.rst, 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 file of documentation in the latex format. An example of the contents of the folder at this stage in the archive is latex_default.zip .
How to generate in PDF only part of the documentation (folder)
We have found such a way out. Using a script, make a copy of the required part, add conf.py to it, i.e. make the piece of documentation be separate documentation. Otherwise, the generation will fail.
3. Changes in latex (.tex file)
If you need to change the basic layout of LaTeX, and the basic settings in conf.py are not enough, change the document template itself, its layout and styles.
There is a preamble in the .tex file (before \ begin {document}), where packages are connected, variables are defined, styles can be described, etc. Here we include 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} Type of presentation
\usepackage{geometry} \geometry{landscape} The .tex file contains the \ maketitle directive, which creates a standard title page using information about the title of the document (\ title), the author (\ author), and the date the text was written (\ date).
We can replace the \ maketitle with your template. We have created for ourselves a separate file TitlePage.tex - the main page template, with which we replace \ maketitle. For different documents use different design templates.
Examples
Table of Contents (toc)
\tableofcontents \phantomsection\label{index::doc} Legal information and copyright 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 any template-completion. So we insert our logo and contacts, and sometimes an external advertising PDF file.
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 into the latex folder, since it is used in our title page template.
4. Generation pdf
We perform the first generation of a PDF document with the command:
pdflatex yourdoc.tex Files appear in the latex folder:
- .aux - information about cross-references
- .toc - table of contents file (table of contents)
- .log - PDF generation log
- .pdf - PDF file. But there is no table of contents
Perform the generation and styling of the table of contents with the command:
makeindex yourdoc.idx We perform repeated and final PDF generation:
pdflatex yourdoc.tex The final PDF file appears in the same folder. An example of the contents of the folder at this stage in the archive is latex_modified.zip .
If you do not make intermediate generations, then the output will be a document without a table of contents. The contents of the toctree root file become the contents of the PDF book. The table of contents of each file becomes the table of contents of each chapter. All links to the table of contents, internal and external links ReST correctly transferred.
If there are errors in ReST (there are no images, incorrect syntax, and the like), then when generating PDF, the pdflatex command will also generate errors and wait for user actions (Enter - skip and continue, H - correct automatically, X - terminate generation). To disable this interactive command, call the command with a parameter that terminates the process at the first error:
pdflatex -halt-on-error yourdoc.tex ReST requirements for generating LaTeX
For the html version, these requirements are non-critical, the documentation will still be formed. But for LaTeX it is fatal. List compiled by experience.
- Must physically exist images that are used in the text.
- By default, the maximum nesting of bulleted and numbered lists is: 3. If more, there will be an error (“LaTeX Error: Too deeply nested”). It is solved this way , verified.
- Listings (source code): for long lines, put hyphens, this will not happen automatically. Otherwise the lines will go beyond the page, will be “cut off”.
- When copying text from somewhere, delete the special characters if they are (emoticons, special characters html).
- It is better that there are no ReST syntax errors.
Also, sometimes the pages are broken inadequately, if there are pictures, tables, blocks of warnings. Then in the rst file you have to set a page break for latex:
.. raw:: latex \newpage Problem with fonts
If a problem occurs, first see the logs - the reasons may be different. We had 2 situations. Add your own in the comments.
One day, the generation stopped working. Tied it up with a server update. We looked at the logs - sphinx began to look for fonts in another folder. We decided through the mount of the folder of fonts, registered it in the server startup.
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 decided to do this by manually starting the generation ( mktextfm <font name> command) for such fonts.
Download for free and without sms
- Example of source documentation in rst: Demo_generation_PDF.tar.gz
- Example of documentation in LaTeX before modification: latex_default.zip
- Example of documentation after the modification of LaTeX and the resulting PDF: latex_modified.zip
- Examples of LaTeX templates: www.latextemplates.com The layout of a complex template is a time eater, if you do not have experience in this - in a limited time it is better to order from someone.
I hope this helps you save a few hours or days when solving a similar problem.
Please report errors in lichku.
Source: https://habr.com/ru/post/328182/
All Articles