Config: avoid default sphinx/mkdocs steps

[agjohnson]

With the addition of build.jobs.builds and friends, we now need to figure out how to avoid the default build jobs/commands that are triggered from the Sphinx/MkDocs builders. This PR illustrates what is happening and needs to change:

• Build: don't run default steps if no sphinx or mkdocs #11810

The caveat here is that some projects still do use the Sphinx builder without specifying the sphinx configuration key. We should find a plan that supports all these use cases, probably without user intervention. Long term, sphinx and mkdocs should be mandatory for using either of these builders.

[stsewd]

We default to use sphinx if none of the options are specified, changing that default will be a breaking change. Maybe we can add another key/option to specify that a "generic" builder is being used, or to signal that all steps shouldn't use the defaults (build.keep_default_jobs: false).

[humitos]

I don't want to add another key for this -it doesn't seem needed and adds a lot of complexity.

What @agjohnson suggested in #11810 (comment) is a good first step here.

if there are build jobs and no sphinx key, we don't do the default steps

---

We default to use sphinx if none of the options are specified, changing that default will be a breaking change.

There are very few projects without sphinx configuration key, and we've been waiting to deprecate this behavior and make sphinx.configuration mandatory (see #10637) --which makes also sphinx and or mkdocs keys mandatory for current projects. We can tell those projects currently not specifying sphinx configuration key to make it explicit; while we implement this feature.

The way to explicitly tell Read the Docs to run default jobs should be by defining mkdocs or sphinx configuration keys. If any of those keys are not defining, there are not default jobs to run.

[agjohnson]

My idea was loose too, there are probably more cases out side build.jobs.build where we shouldn't implicitly use the Sphinx builder too. But the plan feels reasonable at least, projects relying on implicit Sphinx configuration probably aren't going to add build.jobs.build suddenly.

[stsewd]

I think we should first deprecate the default behavior before changing it, or trying to guess if Sphinx should be used or not.

[agjohnson]

Ideally, we would wait for deprecation, but given how important build.jobs.build should be for users, I would not wait for this. This is holding back the build.jobs.build implementation because of a rather small number of projects using the implicit logic. I feel we should make build.jobs.build consistently usable as soon as possible.

[humitos]

I agree with @agjohnson here.

However, @stsewd, you can do both at the same time:

1. Declare a soon deprecation date (eg. Jan 10th; one month from now) --given the low number of projects.
2. Follow the steps written in Deprecation: stop auto-finding conf.py/mkdocs.yml from the repository #10637 (comment).
3. Continue implementing this issue while we wait for that deprecation time.

With the implementation, review and testing time; it will be close to Jan 10th by that time 😄