Support configuration files for sphinx-build to specify common options

[kasium]

Hello,
I'm not sure if this was already requested or discussed somehow but I just couldn't find anything.

Currently, in order to execute my sphinx build I use the setuptools integration which has the big benefit that I have a configuration file which "replaces" cli flags. If I would use sphinx-build I need to specify the source/build dir and all other flags on the CLI which are not supported in conf.py. However, I prefer to have just a simple command like sphinx-build and all other options a picked from a file like setup.cfg.

With the setuptools integration it's not possible to use any other file as far as I know, but I would like to use pyproject.toml exclusively. Therefore my question: Can sphinx support a configuration file like pyproject.toml and just picks there all needed information to execute it's command.

[tool.sphinx]
source_dir = "docs"
build_dir = "docs/_build"

If a user just executes sphinx-build, the source/build dir are used from the config file. A user can also override them by using the related flag/option: sphinx-build -W docs2.

Please note, that this should not replace/extend conf.py but is an extensions before this file is even loaded.

[tk0miya]

Reasonable. +1 for your idea. Contributions are welcome :-)

[kasium]

@tk0miya I can give it a try but I could need some help.

1. I guess the supported options should be equal to the ones build-sphinx supports, right?
2. First, I would add support for the pyproject.toml, is this fine? Should there be an extra requirement to install the toml parser or who should we handle it?
3. Should the user explicitly set the configuration file (e.g. build-spinx --config-file pyproject.toml ) or should we take a look if there is a pyproject.toml with a tool.sphinx section (this is how it's done in most projects). If yes, use it, else nope
4. Any recommendations in which file I should put the code?

Thanks,
Kai

[mgeier]

I'm not sure if this was already requested or discussed somehow but I just couldn't find anything.

Did you have a look at #9040?

But I guess this wouldn't cover source and build directory?

These might be somewhat related: #3132, #4320, #5618, #6938, #6939.

[kasium]

@mgeier thanks for the hint. Yes, I'm aware of this request but I search for a alternative for CLI commands not for the conf.py. E.g. the warning-is-error flag cannot be set in conf.py

@mgeier @tk0miya an alternative would be to allow all settings (beside the source dir obviously) to be set in conf.py. What do you think?

[jakobandersen]

See also #6939, which seems to overlap somewhat with this.
I don't yet see the need for this, but it doesn't sound too unreasonable.

2. First, I would add support for the pyproject.toml, is this fine? Should there be an extra requirement to install the toml parser or who should we handle it?

If I understand correctly, then the pyproject.toml file is specific for Python projects? As Sphinx is used by non-Python projects as well the implementation should probably lend it self to easily support other files in the future.

3. Should the user explicitly set the configuration file (e.g. build-spinx --config-file pyproject.toml ) or should we take a look if there is a pyproject.toml with a tool.sphinx section (this is how it's done in most projects). If yes, use it, else nope

As mentioned in #6939 (comment), these command line options are not for package authors, but for package users. So I think the word "config" should not be used in this context, to avoid confusion with conf.py.
Therefore, I also think this feature should only be triggered when a special flag is given, similar to how make mode is triggered by -M, as really it is an advanced script to invoke the ordinary sphinx-build. I don't have a good name for the flag but as an initial suggestion: sphinx-build --auto (which could optionally take a filename as well).

4. Any recommendations in which file I should put the code?

I suggest another file in sphinx/cmd/ with a call from around

sphinx/sphinx/cmd/build.py

Lines 291 to 294 in f9941b9

	if argv[:1] == ['-M']:
	return make_main(argv)
	else:
	return build_main(argv)

[kasium]

@jakobandersen let me check the issue. Thanks a lot.
What is your thought about that

an alternative would be to allow all settings (beside the source dir obviously) to be set in conf.py. What do you think?

[jakobandersen]

What is your thought about that

an alternative would be to allow all settings (beside the source dir obviously) to be set in conf.py. What do you think?

I am very much against that: conf.py is written by the author of the documentation, the arguments for sphinx-build are primarily for the user of the documentation (e.g., through packager and a build system).

[kasium]

Thanks a lot for your feedback. Let me take a closer look

[kasium]

Hi all,

so I had some further thoughts about this:

1. Expand sphinx/sphinx/cmd/build.py with a new cli parameter called "ini-args-file"
2. If this argument is set a list of file loaders will try to parse the file
3. Each loader has a "can_load" method which is called beforehand to check if e.g. the file is a toml file. The loader which returns true will be used
4. The loader will then load all possible arguments from the file
5. Afterwards the cli arguments are read and will override the file arguments if needed

Suggestion for the toml file (use the same names as the cli argument destination variables)

[tool.sphinx]
builder = ["linkcheck", "html"]
sourcedir = "docs"
jobs = 3

Any feedback to this? I guess it's not very complicated implementation wise. It's extensible and keeps the difference between package author and user.

[kasium]

Any feedback, ideas, suggestions?