Skip to content

Generating PDF manuals

Jump to bottom Edit New page
Henryk Paluch edited this page May 18, 2024 · 27 revisions

Here are ad-hoc guides how to generate PDF versions of open source manuals

Building Debian Packages with git-buildpackage

Official docs are HTML only (including public pages):

I used these commands to build PDF version on Debian 10:

sudo apt-get install python-setuptools xsltproc gtk-doc-tools docbook-to-man dblatex

mkdir -p ~/src
cd ~/src
apt-get source git-buildpackage
cd git-buildpackage-0.9.14/docs
mkdir output
cd output
gtkdoc-mkpdf module1 ../manual.xml

There should be created new PDF file called module1.pdf

Used docs:

Jenkins Job Builder

Generates Jenkins Job from YAML template.

This one is living nightmare - tested on Debian 10...

sudo apt-get install git make python-sphinx python-pip \
     python-yaml python-pbr python-stevedore python-fasteners \
     python-sphinxcontrib.programoutput latexmk \
     texlive-latex-recommended texlive-fonts-recommended \
     texlive-latex-extra     
sudo pip install  jenkins-job-builder

mkdir -p ~/projects
cd ~/projects
git clone https://opendev.org/jjb/jenkins-job-builder.git
cd jenkins-job-builder
python setup.py build
sudo python setup.py install
cd doc
# but see text below...
make latexpdf

Errors and workarounds:

Reference warnings treated as errors. Workaround is to disable treating warnings as errors (remove -W option) - with this change in doc/Makefile:

diff -u Makefile{.orig,}
--- Makefile.orig	2020-12-07 11:07:20.405219969 +0000
+++ Makefile	2020-12-07 11:07:50.009080074 +0000
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W
+#SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

LaTeX reports LaTeX Error: Too deeply nested. fatal error. To resolve this issue:

  • copy original LaTeX format file to your HOME (must be in home!):

    cp /usr/share/texlive/texmf-dist/tex/latex/base/latex.ltx ~/

  • And make this change to ~/latex.ltx

    diff -u /usr/share/texlive/texmf-dist/tex/latex/base/latex.ltx ~/latex.ltx
--- /usr/share/texlive/texmf-dist/tex/latex/base/latex.ltx	2018-12-11 22:32:49.000000000 +0000
+++ /home/ansible/latex.ltx	2020-12-07 14:31:35.162900923 +0000
@@ -4698,7 +4698,7 @@
 \newif\if@noitemarg \@noitemargfalse
 \newif\if@nmbrlist  \@nmbrlistfalse
 \def\list#1#2{%
-  \ifnum \@listdepth >5\relax
+  \ifnum \@listdepth >50\relax
     \@toodeep
   \else
     \global\advance\@listdepth\@ne
@@ -4899,7 +4899,7 @@
 \let\endenumerate =\endlist
 \newcount\@itemdepth \@itemdepth = 0
 \def\itemize{%
-  \ifnum \@itemdepth >\thr@@\@toodeep\else
+  \ifnum \@itemdepth >50\@toodeep\else
     \advance\@itemdepth\@ne
     \edef\@itemitem{labelitem\romannumeral\the\@itemdepth}%
     \expandafter

  • now rebuild all TeX formats:

    rm -rf ~/.texlive2018/
fmtutil-user --all

  • clean build directory and run LaTeX again:

    cd ~/projects/jenkins-job-builder/doc
make clean latexpdf

OpenNebula

GitHub docs are on:

Tested on Debian 11 as of 2022-03-10:

Prepare environment using:

sudo apt-get install git make python3-sphinx-rtd-theme \
     python3-yaml python3-dev python3-pip 

# DO NOT use this package: (v1.3)
# sudo apt-get install python3-sphinx-prompt
# it will fail with error when building docs

sudo pip3 install sphinx-prompt
# installed v 1.5 in my case

mkdir ~/projects
cd ~/projects
git clone https://github.com/OpenNebula/docs.git
cd docs/
# I used exaclty this version of Docs:
git checkout release-6.2.1

Try HTML version first:

# should proceed without error:
make html

Install required (PDF)LaTex packages:

sudo apt-get install latexmk texlive-latex-recommended \
  texlive-fonts-recommended texlive-latex-extra \
  texlive-xetex

Now try (PDF)LaTeX version:

make latexpdf LATEXMKOPTS="-xelatex"

Unfortunately it will generate only:

  • build/latex/opennebula_6.2_intro_release_notes.pdf To generate other PDF files you need to update source/conf.py. Here is example for Quick Start:
diff --git a/source/conf.py b/source/conf.py
index fe057628..76cd2f28 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -222,27 +222,9 @@ latex_documents = [
     latex_author,
     'manual'),
 
-  ( 'deployment/index',
-    file_main_title  + 'deployment_guide.tex',
-    guide_main_title + 'Deployment guide',
-    latex_author,
-    'manual'),
-
-  ( 'operation/index',
-    file_main_title  + 'operation_guide.tex',
-    guide_main_title + 'Operation Guide',
-    latex_author,
-    'manual'),
-
-  ( 'advanced_components/index',
-    file_main_title  + 'advanced_components_guide.tex',
-    guide_main_title + 'Advanced Components Guide',
-    latex_author,
-    'manual'),
-
-  ( 'integration/index',
-    file_main_title  + 'integration_guide.tex',
-    guide_main_title + 'Integration Guide',
+  ( 'quick_start/index',
+    file_main_title  + 'quick_start.tex',
+    guide_main_title + 'Quick Start',
     latex_author,
     'manual'),
 ]

TODO: Convert svg to png etc...

Printing manual pages to PDF

Tested on Debian10.

Install groff:

sudo apt-get install groff

Example printing bash(1) manual to PDF:

mkdir -p ~/manuals
cd ~/manuals
cp /usr/share/man/man1/bash.1.gz .
gzip -d bash.1.gz
groff -T pdf -man bash.1 > bash.1.pdf
# simple check
file bash.1.pdf
# output/bash.1.pdf: PDF document, version 1.4

Jekyll blog generator

WARNING! This conversion is incomplete, but it is better than nothing.

Tested on Debian 10.

Install requirements:

sudo apt-get install pandoc texlive-xetex

NOTE: xelatex is required to process Unicode characters. Regular LaTeX would bail out with error like:

! Package inputenc Error: Unicode character ├ (U+251C)
(inputenc)                not set up for use with LaTeX.

(Jekyll documents use Unicode frames in tree outputs).

Now checkout Jekyll documentation source (MarkDown files):

mkdir -p ~/projects
cd ~/projects
git clone --depth 1 https://github.com/jekyll/jekyll.git
cd jekyll

And generate PDF from files that you are interested, for example:

pandoc --pdf-engine=xelatex -o ~/jekyll-unicode.pdf \
          -V 'mainfont:DejaVuSerif' \
          -V 'sansfont:DejaVuSans' \
          -V 'monofont:DejaVuSansMono' \
          -V 'mathfont:TeXGyreDejaVuMath-Regular' \
  pages.md posts.md front-matter.md collections.md \
  datafiles.md assets.md static_files.md

The -V ... arguments are grabbed from:

They are necessary to avoid these warnings with default fonts:

[WARNING] Missing character: There is no ├ in font [lmmono10-regular]:!

Tips:

  • Pandoc is written in Haskell (!) - if you are looking for real-world (and really big) example of using that language - see https://pandoc.org/installing.html#compiling-from-source how to obtain Haskell sources of Pandoc, or under Debian use standard command apt-get source pandoc.

Fedora Koji manual

Koji is Fedora build system:

To build docs we have to convert single svg image to png. You must have installed working Sphinx with full LaTeX and ImageMagick for convert command. In my example I did:

mkdir ~/projects
git clone --depth=1 https://pagure.io/koji.git
cd koji/docs
( cd source && convert koji_structure1.svg koji_structure1.png

Now replace picture name as shown in diff below:

 diff -u source/index.rst{.orig,}
--- source/index.rst.orig	2021-10-07 17:05:07.084369901 +0200
+++ source/index.rst	2021-10-07 16:58:33.593841015 +0200
@@ -88,7 +88,7 @@
 Koji Components
 ===============
 
-.. figure:: koji_structure1.svg
+.. figure:: koji_structure1.png
    :scale: 50 %
    :alt: Koji component structure diagram

Finally you can run build command:

make latexpdf

Above command should build PDF manual as build/latex/Koji.pdf

OpenEBS PDF manual

Official OpenEBS website is on:

It uses Docusaurus to generate web pages.

I made this project to export OpenEBS website to PDF using Puppeteer:

Again Using Puppeteer

Please also see:

Avocado

Additionally to Sphinx install XeLaTeX to support Unicode characters:

sudo apt-get install texlive-xetex

And now:

git clone --depth=5 https://github.com/avocado-framework/avocado.git
cd avocado/docs/
make html # pilot build

# now PDF stuff
make latexpdf LATEXMKOPTS="-xelatex"
# if you get .svg image errors, remove them
# from source/quickstart/index.rst

Apache AirFlow

Work in progress - tested under Ubuntu 20:

sudo apt-get install docker-compose
# ensure that you are in group 'docker' before continue
mkdir -p ~/projects
cd ~/projects
git clone -b 2-2-stable https://github.com/apache/airflow.git
cd airflow
# test: this will generate html docs for apache-airflow only:
./breeze build-docs -- --package-filter apache-airflow
# look into docs/_build

Try this hack to build EPUB instead:

diff -u docs/exts/docs_build/docs_builder.py{.xxxx,}
--- docs/exts/docs_build/docs_builder.py.xxxx	2022-01-22 15:28:04.177476693 +0000
+++ docs/exts/docs_build/docs_builder.py	2022-01-22 15:48:36.975860350 +0000
@@ -217,7 +217,7 @@
             "-T",  # show full traceback on exception
             "--color",  # do emit colored output
             "-b",  # builder to use
-            "html",
+            "epub",
             "-d",  # path for the cached environment and doctree files
             self._doctree_dir,
             "-c",

Hmm dos not work...

Charm Guide

Docs: https://docs.openstack.org/charm-guide/latest/index.html Gitea Source: https://opendev.org/openstack/charm-guide

Tested on Debian 11:

sudo apt-get install git make python3-sphinx python3-pip \
     python3-yaml python3-pbr python3-stevedore python3-fasteners \
     python3-sphinxcontrib.programoutput latexmk \
     texlive-latex-recommended texlive-fonts-recommended \
     texlive-latex-extra
sudo apt-get install git make python3-sphinx-rtd-theme      python3-yaml python3-dev python3-pip 
sudo apt-get install tox apt-file libpcre3-dev python3-enchant texlive-xetex

Prepare sources:

mkdir -p ~/projects
cd ~/projects
git clone https://opendev.org/openstack/charm-guide.git
cd charm-guide/
git branch -v

  * master 78fe516 Stable hostname for nova-compute service

Try HTML version first:

tox

Not finished yet:

  • apply this patch:

    diff --git a/tox.ini b/tox.ini
index 8fc8e66..2511b23 100644
--- a/tox.ini
+++ b/tox.ini
@@ -19,5 +19,5 @@ commands = sphinx-build -j auto -d doc/build/doctrees -b linkcheck doc/source do
 commands = sphinx-build -j auto -W -d doc/build/doctrees -b html -b spelling doc/source doc/build/html
 
 [testenv:docs]
-commands = sphinx-build -j auto -W -d doc/build/doctrees -b html doc/source doc/build/html
+commands = sphinx-build -j auto -W -d doc/build/doctrees -b latex doc/source doc/build/latexpdf
            whereto doc/source/_extra/.htaccess doc/test/redirect-tests.txt

  • run tox again

  • then try:

    cd doc/build/latexpdf/
make
# Ummm, errors...
# Simply remove whole offending `eqnarray*` block from `CharmGuide.tex` :-)
``

Gentoo

Gentoo python guide from:

WARNING! Generated on Arch Linux (I was too lazy to install LaTeX on Sphinx on Gentoo - but I plan to do it in future):

sudo pacman -S --needed make git
sudo pacman -S --needed python-sphinx graphviz texlive-binextra \
    texlive-latex texlive-latexextra texlive-fontsrecommended imagemagick
mkdir -p ~/projects
cd ~/projects
git clone https://github.com/projg2/python-guide.git
cd python-guide
# just test that it works
make html
# use "latex" only - we need to tweak it a bit
make latex
cd _build/latex
# convert SVG to PNG (LaTeX does not handle SVG)
convert eclass.svg eclass.png
# edit file below and replace .svg with .png
vim gentoopythonguide.tex
# finally generate pdf
make all-pdf
file gentoopythonguide.pdf 

  gentoopythonguide.pdf: PDF document, version 1.5

Early Gentoo notes:

  • I globally enabled USE="svg" in /etc/portage/make.conf

  • emerged graphviz, provides dot command media-gfx/graphviz

  • imagick is tricky - just enabling svg will cause emerge failure due missing xml - we have to also enable xml

  • to fix it try:

    echo 'media-gfx/imagemagick xml svg jpeg webp' >> /etc/portage/package.use/imagick
emerge -av media-gfx/imagemagick

  • here are manually installed tex related packages (from /var/lib/portage/world):

     $ fgrep dev-tex /var/lib/portage/world

 dev-tex/latexmk
 dev-texlive/texlive-formatsextra
 dev-texlive/texlive-langczechslovak
 dev-texlive/texlive-latexextra
 dev-texlive/texlive-latexrecommended
 dev-texlive/texlive-mathscience
 dev-texlive/texlive-metapost
 dev-texlive/texlive-publishers
 dev-texlive/texlive-xetex

  • please note that I had already installed most sphinx packages (including dev-python/sphinx-rtd-theme) because sys-fs/btrfs-progs with USE="man" depends on it - so it is not in world list.

  • here are other not so obvious required packages:

    emerge -an dev-tex/latexmk

= Portage developer manual

There is only portage manual:

Here is how I build single page html (in Gentoo):

mkdir -p ~/src
cd ~/src
git clone https://anongit.gentoo.org/git/proj/portage.git
cd portage
mkdir build
cd build
meson setup -Ddoc-formats=xhtml-nochunks ..
# command below will generate multi-page html output:
ninja doc/html
# here is (mostly) single page (but not entierly?):
ninja doc/portage.html
lynx doc/portage.html

Copyright © Henryk Paluch. All rights reserved.

Creative Commons License This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

Add a custom sidebar
Clone this wiki locally