docs: PDF documentation broken

[jdeamicis]

I can't seem to be able to download the PDF documentation generated by read-the-docs. The browser doesn't open the file, and when I try to download it directly, my PDF reader says it's corrupted.

---

Reported from: https://canonical-ubuntu-packaging-guide.readthedocs-hosted.com/en/latest/

[dviererbe]

Thanks for bringing this to our attention!

I can confirm this issue:

• on Ubuntu the Document Viewer reports that the PDF file is damaged
• and Firefox just loads forever

As a workaround for everyone that needs to work with the Ubuntu Packaging Guide in an offline environment I can recommend installing the Snap that serves the documentation from a locally hosted web server.

[dviererbe]

Running make latexpdf does not work at all :/

make -C docs latexpdf
make[1]: Entering directory '/home/dviererbe/Repositories/Canonical/ubuntu-packaging-guide/docs'
. .sphinx/venv/bin/activate; sphinx-build -M latexpdf "." "_build" -c . -d .sphinx/.doctrees 
Running Sphinx v7.3.7
matplotlib is not installed, social cards will not be generated
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
reading sources... 
looking for now-outdated files... none found
copying TeX support files... copying TeX support files...
done
processing ubuntu-packaging-guide.tex... index tutorial tutorial/getting-set-up tutorial/make-changes-to-package tutorial/create-new-package tutorial/fix-bug how-to how-to/get-package-source how-to/download-new-upstream-version how-to/build-packages how-to/install-built-packages how-to/run-tests how-to/upload-packages-to-ppa how-to/write-patchfiles how-to/propose-changes how-to/use-schroots explanation explanation/upstream-and-downstream explanation/package-model explanation/development-process explanation/releases explanation/archive explanation/launchpad explanation/sponsoring explanation/proposed-migrations explanation/stable-release-updates explanation/debian-syncs explanation/debian-merges explanation/transitions explanation/backports explanation/main-inclusion-review reference reference/debian-dir-overview reference/architectures reference/package-tests reference/package-version-format reference/git-ubuntu reference/apt reference/debian-policy reference/filesystem-hierarchy-standard reference/outdated-tools reference/launchpad-text-markup reference/glossary contribute 
resolving references...
done
writing... done
copying images... [100%] images/reference/glossary/Old-Ubuntu-Login-Background.jpg
build succeeded.

The LaTeX files are in _build/latex.
Run 'make' in that directory to run these through (pdf)latex
(use `make latexpdf' here to do that automatically).
make[2]: Entering directory '/home/dviererbe/Repositories/Canonical/ubuntu-packaging-guide/docs/_build/latex'
latexmk -pdf -dvi- -ps-  'ubuntu-packaging-guide.tex'
make[2]: latexmk: No such file or directory
make[2]: *** [Makefile:29: ubuntu-packaging-guide.pdf] Error 127
make[2]: Leaving directory '/home/dviererbe/Repositories/Canonical/ubuntu-packaging-guide/docs/_build/latex'
make[1]: *** [Makefile:105: latexpdf] Error 2
make[1]: Leaving directory '/home/dviererbe/Repositories/Canonical/ubuntu-packaging-guide/docs'
make: *** [Makefile:5: latexpdf] Error 2

To set expectations: I will wait to work on solving this until the new Sphinx Extension at canonical/sphinx-docs-starter-pack has been landed, because when we migrate it will change the configuration files fundamentally.

[dviererbe]

@s-makin told me that someone fixed the PDF issue for a documentation project from the Ubuntu Server team. I still recommend waiting to fix this until we migrated to the new sphinx extension to avoid potential duplicate work.

[SecondSkoll]

Cloning this repo and looking at the local PDF build, the only critical error here that I can see preventing the build is the inclusion of an SVG image in the glossary. Just deleting that image reference allows the PDF to build - which results in this.

Essentially SVGs don't contain data on their actual size, so LaTeX just doesn't know how to deal with them without specific packages and environments. It's just a fundamental issue with trying to use an infinitely scalable image in a way that doesn't define the scale - which is how Sphinx's default LaTeX environments deal with images.

@s-makin let me know about this issue (I'm the one who helped over with Ubuntu Server), so I'll put together a PR which will fix the build and update you to the new branding as well.

The move to put everything into an extension will likely take another month or two, AFAIK, and this fix won't take long. Configuration files in general wont be changing so much as being rearranged so it won't have significant impact (and if that changes I'm happy to pitch in and make sure my actions here don't affect you and your team negatively). I'll also fix any other issues I come across - but I was unable to replicate the error log above.

[dviererbe]

@SecondSkoll if it is not a lot of work than you are very welcome to open PR to fix PDF building :)

Regarding the new branding. Would it be possible to have a cover that would not waste a lot of ink if printed?