sphinx-doc / sphinx-doc/sphinx

Custom latex_elements for each latex_document

Open
#9,145 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:latex type:enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.