Use hatch on RTD

[grst]

Trying to get RTD to build the docs with hatch.
If this works, it would be an alternative to #400

[github-actions]

A PR has been generated to the instance repo:
scverse/cookiecutter-scverse-instance#204

You can check out the PR to preview your changes
in an instance of the cookiecutter template. The PR will be kept in sync with
this PR automatically.

[grst]

Down from 44s to 26s.

[Zethson]

Great!

However, I wonder whether we lose the fail on warning here.

cookiecutter-scverse/{{cookiecutter.project_name}}/pyproject.toml

Line 71 in 1bf0b54

scripts.build = "sphinx-build -M html docs docs/_build {args}"

does not have a -W and we're deleting the sphinx section.

[grst]

it should probably be added to pyproject.toml then.

[Zethson]

Now I think it should be good.

[grst]

Not sure why we didn't have this in pyproject.toml until now? if we think it's desirable to only have this enabled on RTD by default, the -W flag could also be appended to the hatch run command.

[Zethson]

Actually, why does this work?

https://about.readthedocs.com/blog/2024/12/deprecate-config-files-without-sphinx-or-mkdocs-config/

We should need a configuration key.

[flying-sheep]

Read the last sentence of your link:

If you are using the build.commands feature, you don't need to make any changes, as the sphinx and mkdocs options are not required when using build.commands.

[flying-sheep]

About the -W flag: since Sphinx 8.1 it no longer cancels the build, so we get a -1 exit code and also fully built docs, which I think is perfect for the CLI. “Something is wrong” but you can inspect the complete docs.

I wish it was possible to have RTD’s PR status check fail while also having it upload the docs, that would be perfection.

I updated the dependency to sphinx >=8.1 so users can rely on that behavior.

[grst]

I think if you provide a custom build command, the entire sphinx: context is ignored