I am struggling to get my documentation built on readthedocs. Locally, everything works fine, but there seems to be something wrong with my .readthedocs.yaml file:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"

sphinx:
  configuration: conf.py
  output_dir: $READTHEDOCS_OUTPUT/html

formats:
  - pdf
  - epub
  - htmlzip

python:
  install:
    - requirements: requirements.txt

The build fails with the message:

Error Make sure the key name sphinx.output_dir is correct.

If I try to comment the output_dir: $READTHEDOCS_OUTPUT/html line, in the hope that readthedocs figures out the output directory automatically, the build fails with the message:

Error Some files were detected in an unsupported output path: _build/html. Ensure your project is configured to use the output path $READTHEDOCS_OUTPUT/html

Any suggestions? (the git repository for the documents can be found at )

I am struggling to get my documentation built on readthedocs. Locally, everything works fine, but there seems to be something wrong with my .readthedocs.yaml file:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"

sphinx:
  configuration: conf.py
  output_dir: $READTHEDOCS_OUTPUT/html

formats:
  - pdf
  - epub
  - htmlzip

python:
  install:
    - requirements: requirements.txt

The build fails with the message:

Error Make sure the key name sphinx.output_dir is correct.

If I try to comment the output_dir: $READTHEDOCS_OUTPUT/html line, in the hope that readthedocs figures out the output directory automatically, the build fails with the message:

Error Some files were detected in an unsupported output path: _build/html. Ensure your project is configured to use the output path $READTHEDOCS_OUTPUT/html

Any suggestions? (the git repository for the documents can be found at https://github/andremano/GIS-4-Land-Administration)

• python-sphinx
• read-the-docs

• 1 Perhaps there is no key named "output_dir" related to Sphinx. You could try if "outputdir" or "output-dir" works in the yaml file. – hbstha123 Commented Feb 4 at 22:49
• thanks @hbstha123. Good suggestion but did not work. – Lisdengard Commented Feb 4 at 23:04
• 1 output_dir is not a valid key. See docs.readthedocs/platform/stable/config-file/v2.html#sphinx. Delete the line. – Steve Piercy Commented Feb 5 at 7:07
• Thanks @StevePiercy. Indeed, it does not, but if I remove it then I get the "Error Some files were detected in an unsupported output path: _build/html. Ensure your project is configured to use the output path $READTHEDOCS_OUTPUT/html", so I am feeling very lost. – Lisdengard Commented Feb 5 at 8:23
• 1 Got link to RTD build log? I think something earlier fails. – Steve Piercy Commented Feb 5 at 12:53

1 Answer 1

Thank you everyone for the time and suggestions you took with this question.

It appears this problem came from the Sphinx version used during the first build.The documents were built using Sphinx 4.X back in 2020 or so.

I knew this, so I upgraded my Sphinx before trying to publish my updated documents into readthedocs. I believe here is where the problem lies, although I cannot pinpoint precisely where/why, but it may be the case that the the structure and elements of Sphinx 4.X are not fully supported/ported to the latest Sphinx version.

Long Story short, I simply rebuilt my documentation from scratch by running a sphinx-quickstart in a new folder and then copying the documentation .rst files and configurations into the new folder.