Build: fail build if conf.py file doesn't exist

[witolddebski]

Details

I am trying to build the docs for the first time and I am receiving the following error:

root file /home/docs/checkouts/readthedocs.org/user_builds/gestrec/checkouts/latest/docs/index.rst not found
The docs build locally without any warnings.

• Read the Docs project URL: https://readthedocs.org/projects/gestrec/
• Build URL (if applicable): https://readthedocs.org/projects/gestrec/builds/21591531/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/witolddebski/

Expected Result

docs build successfully, just like locally

Actual Result

I got the above error. I noticed that the filepath in the error is ".../latest/docs/index.rst" and all my source files are in folder docs/source, so I set the following variables to try and fix the issue:

master_doc = 'index'
root_doc = 'index'

I also tried:

master_doc = 'source/index'
root_doc = 'source/index'

it did not fix the issue.

I suspect it is somehow not picking up my conf.py file, since I am also getting an error /home/docs/checkouts/readthedocs.org/user_builds/gestrec/checkouts/latest/docs/source/reference.rst:4: ERROR: Unknown directive type "automodule". which I'm not getting locally, as I have the extension defined in conf.py

help plz

[jayunit100]

yeah, im also seeing this....

seems like the intro doc is out of date, as another issue #10626 is also happening

/home/docs/checkouts/readthedocs.org/user_builds/storyworld0/checkouts/latest/docs/source/usage.rst:21: ERROR: Unknown directive type "autofunction".

.. autofunction:: lumache.get_random_ingredients
/home/docs/checkouts/readthedocs.org/user_builds/storyworld0/checkouts/latest/docs/source/usage.rst:27: ERROR: Unknown directive type "autoexception".

.. autoexception:: lumache.InvalidKindError

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/storyworld0/envs/latest/lib/python3.11/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/storyworld0/envs/latest/lib/python3.11/site-packages/sphinx/application.py", line 353, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/storyworld0/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 311, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/storyworld0/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 328, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/storyworld0/envs/latest/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 438, in read
    raise SphinxError('root file %s not found' %
sphinx.errors.SphinxError: root file /home/docs/checkouts/readthedocs.org/user_builds/storyworld0/checkouts/latest/docs/index.rst not found

Sphinx error:
root file /home/docs/checkouts/readthedocs.org/user_builds/storyworld0/checkouts/latest/docs/index.rst not found

[jayunit100]

Ok, I got it working using your clue above, moved files around:

• got rid of everything in source/
• made lumache importable by giving it an init package : https://github.com/jayunit100/storyworld0/tree/main/docs
• aligned it with the https://github.com/jayunit100/storyworld0/blob/main/.readthedocs.yaml file

so the new tree looks like

├── README.rst
├── docs
│   ├── Makefile
│   ├── __init__.py
│   ├── build
│   ├── conf.py
│   ├── index.rst
│   ├── lumache.py
│   ├── make.bat
│   ├── requirements.txt
│   ├── source
│   │   ├── generated
│   │   ├── index.rst
│   │   └── usage.rst
│   └── usage.rst
└── pyproject.toml

[witolddebski]

I got it, sphinx quickstart build puts conf.py in folder source, while in .readthedocs.yaml I had docs/conf.py instead of docs/source/conf.py.

It seems the config file was not found during the build. It would be nice if we could get a warning when the config file is not found.

[stsewd]

It seems the config file was not found during the build. It would be nice if we could get a warning when the config file is not found.

+1 on this, looks like we are currently just appending our custom overrides even if the file doesn't exist

readthedocs.org/readthedocs/doc_builder/backends/sphinx.py

Lines 292 to 294 in f4efd14

	outfile = safe_open(
	self.config_file, "a", allow_symlinks=True, base_path=self.project_path
	)

[humitos]

This is already deprecated #2483 and it will be completely removed on August 28th. Read more about this at https://blog.readthedocs.com/doctool-without-configuration-file/

[stsewd]

@humitos looks like that's only deprecating projects that don't explicitly set their conf.py file, projects that have it set, but it doesn't point to an existing location aren't being included in that deprecation. Since we open the file with mode a, if the file doesn't exist, one is created.

[humitos]

I'll check that case. We should remove it if it's not contemplated in that PR already.

[humitos]

@stsewd I added a new commit eef1165 (#5609) to #5609 that fails the build if the config file doesn't exist.