godotengine / godotengine/godot-docs

Building PDF, WIP

Open
#8,605 0 comments 4 reactions 0 assignees View on GitHub
content:website enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**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](https://github.com/godotengine/godot-docs/files/13639140/GodotEngine.pdf)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.