bypass sphinx conf.py from CLI
Hi,
The StarlingX docs team is implementing the default sphinxcontrib.spelling spelling extension for use from tox via a virtualenv set up for this purpose. We do not want sphinxcontrib.spelling loaded into other tox jobs that won't use it. This means that it cannot be loaded from the standard conf.py. Instead I am bypassing conf.py and setting parameters from the sphinx-build command in the appropriate tox job:
sphinx-build -a -E -C --keep-going -d doc/build/doctrees -D extensions=sphinxcontrib.spelling -D spelling_word_list_filename=spelling_wordlist.txt -D rst_prolog="open('./shared/strings.txt', 'r').read()" -t starlingx -t openstack -b spelling doc/source doc/build/spelling {posargs}
This works except that we also need to load some strings into the rst prolog for various purposes, and that is failing without warning or errors. I can open the file from a python console. Sphinx-build escapes the single quotes as:
open('"'"'./shared/strings.txt'"'"', '"'"'r'"'"').read()'
Any suggestions on the correct parameter format appreciated.
Ron
On 2022-02-02 20:49:05 +0000 (+0000), Stone, Ronald wrote:
The StarlingX docs team is implementing the default sphinxcontrib.spelling spelling extension for use from tox via a virtualenv set up for this purpose. We do not want sphinxcontrib.spelling loaded into other tox jobs that won't use it. This means that it cannot be loaded from the standard conf.py. Instead I am bypassing conf.py and setting parameters from the sphinx-build command in the appropriate tox job:
[...]
Have you considered creating a separate doc/source/conf-spelling.py and passing that via sphinx-build's -c option instead?
On Wed, 2022-02-02 at 22:09 +0000, Jeremy Stanley wrote:
On 2022-02-02 20:49:05 +0000 (+0000), Stone, Ronald wrote:
The StarlingX docs team is implementing the default sphinxcontrib.spelling spelling extension for use from tox via a virtualenv set up for this purpose. We do not want sphinxcontrib.spelling loaded into other tox jobs that won't use it. This means that it cannot be loaded from the standard conf.py. Instead I am bypassing conf.py and setting parameters from the sphinx-build command in the appropriate tox job:
[...]
Have you considered creating a separate doc/source/conf-spelling.py and passing that via sphinx-build's -c option instead?
Also remember that the 'conf.py' is a Python file so you can encode logic in it. tox injects environment variables when running [1]. It would be easy to check for the presence of e.g. 'TOX_ENV_NAME' and add the extension as necessary.
Stephen
[1] https://tox.wiki/en/latest/config.html#injected-environment-variables
participants (3)
-
Jeremy Stanley
-
Stephen Finucane
-
Stone, Ronald