-
Notifications
You must be signed in to change notification settings - Fork 8
Generating PDF manuals
Here are ad-hoc guides how to generate PDF versions of open source manuals
Official docs are HTML only (including public pages):
- online: https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/ (referenced from: https://wiki.debian.org/PackagingWithGit?action=print)
- as part of Debian 10 package
git-buildpackage
:/usr/share/doc/git-buildpackage/manual-html/
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:
Generates Jenkins Job from YAML template.
- Online docs: https://jenkins-job-builder.readthedocs.io/en/latest/index.html
- Git repo: https://opendev.org/jjb/jenkins-job-builder
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
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 updatesource/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...
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
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
.
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
Official OpenEBS website is on:
It uses Docusaurus to generate web pages.
I made this project to export OpenEBS website to PDF using Puppeteer:
Please also see:
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
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...
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 python guide from:
- online: https://projects.gentoo.org/python/guide/preface.html
- source: https://github.com/projg2/python-guide
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
commandmedia-gfx/graphviz
-
imagick is tricky - just enabling
svg
will cause emerge failure due missingxml
- we have to also enablexml
-
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
) becausesys-fs/btrfs-progs
withUSE="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:
- https://dev.gentoo.org/~zmedico/portage/doc/ But it is multi-page (not suitable for PDF export and/or mobi or other formats)
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.
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License