sphinx-doc / sphinx-doc/sphinx

Make complex setting values like latex_documents overridable

Open
#12,438 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api:cmdline type:proposal
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 want to override latex specific settings when invoking sphinx-build to embed the generated latex in an external document. I do not want to edit the original conf.py. First I tried a dedidcated conf.py but ran into problems with relative paths so I decided to try the command line settings override.

The --define documentation nicely explains how to override dict and list type values. However, latex_documents is a list of tuples which are not handled correctly.

Describe the solution you'd like
I do not have a favourite solution.

My original problem of patching "conf.py" without file modification can also be solved by additional "appendable" python code.

Describe alternatives you've considered

  • Make list entries addressable by <name>.<index> notation
  • Intoduce dedicated syntax for latex_document entry that does not use ,
  • Add a dedicated --json-settings argument which accepts a JSON object. This can be tricky to use because shells treat quotes differently.

Additional context
Parsing of list type values (btw: There is no way to escape the ","): https://github.com/sphinx-doc/sphinx/blob/6471027d1936f0a0a38ef281862f0b29c53618f6/sphinx/config.py#L342

Interpretation of list elements as sequence in the latex builder: https://github.com/sphinx-doc/sphinx/blob/6471027d1936f0a0a38ef281862f0b29c53618f6/sphinx/builders/latex/__init__.py#L150

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 with the --define documentation and the list-value parsing in sphinx/config.py around line 342, then inspect how the LaTeX builder interprets sequence values around sphinx/builders/latex/init.py line 150. Compare the proposed override approaches and establish a supported way to override latex_documents without editing conf.py; done means complex values are parsed and applied correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.