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. I ignored Overview and 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 to inject styling instead of defining each object's environment from scratch but I suppose that's the issue for the template itself, right?
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. I ignored Overview and Configure document properties completely.
First of all, the code doesn't work when copied as is:
astlatex_elementsfirstSecond, 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_elementsin conf.py directly. This option is mentioned as aWarningat the end of instructions: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_extensionand 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 to inject styling instead of defining each object's environment from scratch but I suppose that's the issue for the template itself, right?