Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build: use Sphinx configuration file explicitly #9713

Open
agjohnson opened this issue Nov 5, 2022 · 2 comments
Open

Build: use Sphinx configuration file explicitly #9713

agjohnson opened this issue Nov 5, 2022 · 2 comments
Labels
Bug A bug Needed: design decision A core team decision is required

Comments

@agjohnson
Copy link
Contributor

agjohnson commented Nov 5, 2022

A user reported a bug with our Sphinx configuration file handling and I'm actually surprised we haven't noticed it before.

Though we provide projects with a way to specify the configuration file path, we don't actually explicitly pass this path into Sphinx. If a project uses a configuration file that is not named conf.py, Sphinx will error out.

The code here just seems to set the working path to the configuration directory and assumes that the file will always be named conf.py.

This maybe isn't a strong use case to fix with application code, but I'd agree it is rather confusing. We could change the call to Sphinx, or throw a warning, or maybe just document the issue somewhere, no strong preference.

Test build for illustration: https://readthedocs.org/projects/test-builds/builds/18548005/

@agjohnson agjohnson added Needed: design decision A core team decision is required Bug A bug labels Nov 5, 2022
@agjohnson
Copy link
Contributor Author

I've never had a need to use this pattern, but I thought that sphinx-build -c docs/conf-foo.py was enough. It actually is not, as this is strictly just the path to the config file. Guessing there isn't a great way around this, at least not once that's obvious, so might just be worth documenting.

@humitos
Copy link
Member

humitos commented Jan 31, 2023

We should probably validate that sphinx.configuration value ends with /conf.py 😄 and raise an exception otherwise.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Bug A bug Needed: design decision A core team decision is required
Projects
None yet
Development

No branches or pull requests

2 participants