build fails silently when conf.py is missing

[taylorhummon]

Details

I used the example .readthedocs.yaml found here:
https://docs.readthedocs.io/en/stable/config-file/v2.html#id1

Note that the sphinx configuration file path is listed as:
docs/conf.py
instead of the default path:
docs/source/conf.py

When I tried to build my project, the build could not find conf.py and it failed silently.
I would recommend updating the documentation to use the default path so that others don't get tripped up by this.

Expected Result

The build should fail and explain why it failed: it cannot find the sphinx configuration file at docs/conf.py.

Actual Result

The build failed and there was no indication of why it had failed.

[taylorhummon]

Note that the .readthedocs.yaml example on the reproducible builds page also has the non-default path:
https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#id1

[agjohnson]

Thanks for the feedback. The first path docs/conf.py is more common we've found, as it's not common to use a separate source path. If you select to use a separate source path for your files during the Sphinx quick start, that is when you should use a path like docs/source/. However, even prefixing with docs/ is just an example, this is not a standard configured path either.

These paths are just examples, we leave it up to maintainers to determine the correct path.

[agjohnson]

The build failed and there was no indication of why it had failed.

And this sounds like it could be a bug with our notifications, which I believe we had trouble showing to non-maintainer users on the build detail page. If you include information on your project that would help pinpoint the error.

[humitos]

And this sounds like it could be a bug with our notifications, which I believe we had trouble showing to non-maintainer users on the build detail page

I opened an issue to track this at #11146

[cr1901]

Can confirm this also happened to me (my sphinx config was at doc/conf.py): https://readthedocs.org/api/v2/build/23550383.txt

The build silently exits without telling me "hey, I couldn't find a config!"

[agjohnson]

Yeah I think the underlying issue here is the missing notification bug. Normally the error message is pretty actionable here, it states that the configuration wasn't found and what path was attempted.

I'm going to close this in favor of

• Notifications: always show notifications on build details' page #11146