New Read the Docs tutorial, part II

[astrojuanlu]

This is the second pull request for the new Read the Docs tutorial proposed in #8106 in the context of the CZI grant. It is a follow up to #8428.

Rendered version: https://docs--8473.org.readthedocs.build/en/8473/tutorial/

This pull request intends to cover chapter 2 of the table of contents originally proposed in #8106:

3. Customizing the build process
   • Use readthedocs.yaml (rather than the web UI) to customize build formats, change build requirements and Python version, enable fail-on-warnings
4. Versioning documentation
   • Explain how to manage versions on RTD: create release branches, activate the corresponding version, browse them in the version selector, selectively build versions
   • Intermediate topics: hide versions, create Automation Rules

The template mentioned in the tutorial is still living on my personal GitHub account before it is accepted. I made a couple of adjustments for the tutorial.

https://github.com/astrojuanlu/tutorial-template/

[stsewd]

Think we should put the whole content or just the new content to avoid confusions.

[astrojuanlu]

I think it would be a bit tedious to put all the content, and putting a fragment gives some context

[astrojuanlu]

This is now ready for review.

[astrojuanlu]

Opened #8476 with some thoughts about our implicit automations for versions, although I'd prefer to not block the tutorial on it.

[ericholscher]

This looks like a great addition! Just a few small things I noticed, but I think it's close.

[ericholscher]

I think we deprecated this functionality, and replaced it with this extension, apparently without noting that anywhere: https://sphinx-version-warning.readthedocs.io/en/latest/ -- I think we did this to make it more configurable (/cc @humitos).

Not 100% sure if we should include it in the tutorial. If it works, we can go ahead and keep it in tho, unless we really don't want to promote it.

[astrojuanlu]

It works, I tested it with my own project and took a screenshot. If it's deprecated, it's impossible to know, because there's no mention of it in https://docs.readthedocs.io/en/stable/versions.html#version-warning either.

[astrojuanlu]

Thanks @ericholscher! Addressed the second round of feedback 👍🏽

[astrojuanlu]

Since this is approved, I will merge and then add some changes related to our default versions and dependencies in a separate pull request. See discussion on #8473 (comment) and content in https://github.com/readthedocs/readthedocs.org/pull/7859/files#diff-1d854732c488780cf89b325277dd80220a7e541647ccf1c18bdc372eb7b1a4d6R49.