canonical / canonical/sphinx-stack-docs
"Override the LaTeX template" is confusing
- Dominant language
- No language data
- Stars
- 4
- Forks
- 11
- Avg merge
- 13d 16h
- Merged PRs (30d)
- 2
Description
For context: I wanted to change a few cosmetic things about how my PDFs look such font sizes and padding in my tables, I went directly to [Override the LaTeX template](https://canonical-starter-pack.readthedocs-hosted.com/stable/how-to/customise-pdf/#override-the-latex-template). I ignored [Overview](https://canonical-starter-pack.readthedocs-hosted.com/stable/how-to/customise-pdf/#overview) and [Configure document properties](https://canonical-starter-pack.readthedocs-hosted.com/stable/how-to/customise-pdf/#configure-document-properties) completely.
First of all, the code doesn't work when copied as is:
- default conf.py doesn't import `ast`
- no instructions to initialize `latex_elements` first
Second, the immediate solution to overriding defaults is very heavy-handed, if one needs to tweak a small thing or two (such as the font size), copying an entire template and maintaining it in the repo is an overkill when it can be easily done with `latex_elements` in conf.py directly. This option is mentioned as a `Warning` at the _end_ of instructions:
> Defining other settings directly in latex_elements will override the values loaded from the template file or your local file.
I understand the idea behind it -- separation of concerns, etc, but it took me a few extra minutes of back and forth between Sphinx docs and SP docs to realize it.
Also, it is not explained what to do if the default template that is maintained as part of `canonical_extension` and one's project's template diverge significantly at some point. If there is an expectation for all Canonical documentation to maintain a degree of visual consistency (hence why we have a Canonical theme), I would assume the same applies to the PDFs?
Also, I am not a LaTeX expert, so correct me if I'm wrong here, but it would be nice to redesign the template to use [hooks](https://www.latex-project.org/help/documentation/lthooks-doc.pdf) to inject styling instead of defining each object's environment from scratch but I suppose that's the issue for the template itself, right?
Contributor guide
Assessment
This issue has not been assessed yet.