sphinx-doc / sphinx-doc/sphinx
Custom latex_elements for each latex_document
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
I need to define different preambles for different latex_documents, because I need varied metainformation in maketitle.
I can't define the metainformation in the source files, because the output is placed after the maketitle command.
It might be also useful to have other settings in latex_elements defineable for different latex documents.
Describe the solution you'd like
I want to define different settings for each document in latex_documents. The settings should allow different latex_elements for each document and they might even include custom title, author, theme and toctree_only settings, which currently are in latex_documents.
Example
Instead of:
latex_elements = {
'preamble': '<common preamble for all latex docs>',
# other elements
}
latex_documents = [
('doc one source', 'doc one.tex', custom_title, custom_author, theme, toctree_only),
('doc two source', 'doc two.tex', custom_title2, custom_author2, theme2, toctree_only2),
...
]
I'd prefer to have:
latex_documents = [
('doc one source', 'doc one.tex', latex_settings_doc_one),
('doc two source', 'doc two.tex', latex_settings_doc_two),
('doc three source', 'doc three.tex', latex_settings_doc_one),
# I could use the same settings for several docs where possible
...
]
where for example:
latex_settings_doc_one = {
'title': 'Doc One Title',
'author': 'Doc One Author',
'theme': 'howto',
'toctree_only': False,
'preamble': '<doc one preamble goes here>',
# + all other elements of latex_elements would go here
}
Describe alternatives you've considered
I've considered creating a project for every latex document which has to have a different latex_elements config ... but come on! :)
I tried adding my metainformation in the source file, but it goes after maketitle, so no way. I don't have an option to modify how tex files are composed (templating).
Additional context
By metainformation I mean latex commands that work as variables and hold values used later in my custom maketitle that prints additional information about the document in the title -- examples of metainformation: doctype, confidentiality classification, document identifier.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing how the latex_documents and latex_elements configuration entries are consumed when LaTeX output is generated. Compare the requested per-document settings with the existing title, author, theme, and toctree_only options. Done means a coherent configuration path supports distinct settings for each document without requiring separate projects.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- latex, python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100