sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.64k stars 2.13k forks source link

Custom latex_elements for each latex_document #9145

Open Lennonka opened 3 years ago

Lennonka commented 3 years ago

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.

Lennonka commented 3 years ago

I would even appreciate a quick workaround if I'm missing something.

tk0miya commented 3 years ago

It would be nice if we can switch the base template for each latex_documents entry. I still don't understand it covers all of the cases. But it will resolve some of them.