sphinx-doc / sphinx-doc/sphinx

sphinx.cmd.build.main ignores overriding of configuration setting with -D param

Open
#8,235 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

I'm using Sphinx command line module sphinx.cmd.build to generate documentation in multiple languages. The language setting is not stored in the conf.py, but is overridden with -D parameter in the invocation. Surprisingly the overriding works only the first time sphinx.cmd.build.main is called. All next call will ignore the setting, using the previous setting.

This worked out with old Sphinx 1.5.5 (and with old cmdline interface), but after update to newest version is no more functional.

To Reproduce
This is simple code I am using to generate the documentation (with Windows paths):

import sphinx.cmd.build
import sys


if __name__ == '__main__':
    invocation_list = [
        '-bhtml',  # builder is html
       '-Dlanguage=de',  # the additional setting,
        '..\\SphinxTest\\testproject',  # Source directory
         '..\\SphinxTest\\testproject_deutsch',  # Destination directory
    ]

    sphinx.cmd.build.main(invocation_list)

    invocation_list = [
        '-bhtml',  # builder is html
       '-Dlanguage=en',  # the additional setting
        '..\\SphinxTest\\testproject',  # Source directory
        '..\\SphinxTest\\testproject_english',  # Destination directory
    ]

    sphinx.cmd.build.main(invocation_list)
    sys.exit(0)

The document for which documentation should be generated (index.rst):

Is the frame in the correct language???
=======================================


.. toctree::
   :maxdepth: 2
   :caption: Contents:

The conf.py file

project = 'Test of Sphinx'
copyright = '2020, Company'
author = 'Company'
release = '4.0.0.0'

extensions = []
exclude_patterns = []
html_theme = 'alabaster'

Execute the script: the both HTMLs are in German (since the call was the first).

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 provided script and sphinx.cmd.build.main, then compare the first and second invocation using the two invocation_list values. Review how conf.py and the -Dlanguage setting are handled between calls; done means separate German and English HTML outputs are produced as requested.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.