Building PDF, WIP

[peteristhegreat]

Your Godot version: 4.2

Issue description: Printable PDF coming out of sphinx and tlmgr and latex

URL to the documentation page (if already existing):

I got a pdf out of the documentation and I wanted to share my steps. At some point it should get pushed into the Makefiles somehow.

Summary of changes

• enable the pdf format
• install a recent version of tlmgr for latex dependencies
• install the list of latex libraries/modules
• install imagemagick to get convert
• convert webp and gif and svg to png's and update the _build/latexpdf/GodotEngine.tex, too.

TODO

• Maybe comment on the gif files for specific frame numbers that should go to the pdf. For now I am just grabbing the first frame.
• Also the code blocks in the pdf are all in Times New Roman or some sort of Serif font. This should get changed to monospace. But the colors are there and look good.
• The Table of Contents didn't render fully... I probably hit an error and skipped over it.

My build environment: Ubuntu 22.04

Manual steps for getting a pdf out of the Godot Docs...

Update the formats list to include pdf

# .readthedocs.yml, line 22
# formats: [] # change to
formats:
  - pdf

curl -L http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz | tar xz
cd install-tl-*/
sudo ./install-tl
# Adjust options per the tlmgr guidelines here...
# https://en.wikibooks.org/wiki/LaTeX/Installation#Minimal_installation

# Having tlmgr installed and then installing all the latex deps can fix all the
#       ! LaTeX Error: File `cmap.sty' not found.
# errors

# Here's how I installed the sty files... There may be a better way to have tlmgr walk the 
# dep tree in the .tex and sty files...
sudo tlmgr install \
  cmap amscls amsmath babel tex-gyre geometry hyperref \
  hypcap fncychap float wrapfig capt-of framed fancyvrb \
  upquote needspace tabulary varwidth parskip etoolbox \
  titlesec pdftexcmds infwarerr

# The above list was mostly from trial and error of seeing the 
#         cannot find XXX.sty file, please give the file name
# errors during a makefile run in the _build/latexpdf folder

# download the godot-docs repo
git clone --depth 1 https://github.com/godotengine/godot-docs.git
sudo apt-get install -y imagemagick latexmk
python3 -m venv sphinx-env
source ./sphinx-env/bin/activate
pip3 install -r requirements.txt

make
# fails on make pdf step
# 
cd _build/latexpdf/

# Run convert on all the files in the build/latexpdf folder due to errors such as
#            ! LaTeX Error: Unknown graphics extension: .svg.
#  ...
for file in *.webp; do convert "$file" "${file%.webp}.png"; done
for file in *.svg; do convert "$file" "${file%.webp}.png"; done
for file in *.gif; do
  base_name="${file%.gif}"
  convert "${file}[0]" "${base_name}.png"  # [0] indicates the first frame
done

# update all references to the other file types
sed -i 's/\.webp/\.png/g' *.tex
sed -i 's/\.gif/\.png/g' *.tex
sed -i 's/\.svg/\.png/g' *.tex

# These webp files complained in the convert step. 
# I don't know if it is a big problem, or if they just need 
# the `-strip` flag when calling convert

# clion-create-build-tool.webp
# globalclasses_addnode.webp
# globalclasses_createresource.webp
# globalclasses_exportedproperty1.webp
# globalclasses_exportedproperty2.webp
# movement_inputs.webp
# signals_13_signals_connection_icon.webp
# signals_14_signals_connection_info.webp
# subviewportnode.webp texturepath.webp
# vector_subtract2.webp

# from inside the _build/latexpdf/ directory
make

ls -lh *.pdf
-rw-r--r-- 1 ubuntu ubuntu 12M Dec  8 18:56 GodotEngine.pdf

I still got warnings and errors in this, but I was able to push through. Honestly for me, I wanted to dig through the Best Practices with a highlighter or pen in hand to take notes, and this fit the bill nicely.

GodotEngine.pdf