Post: enable addons by default

[humitos]

Follows the plan we described in:
readthedocs/addons#72 (comment)

---

📚 Documentation preview 📚: https://readthedocs-about--308.org.readthedocs.build/blog/2024/07/addons-by-default/

[ericholscher]

I feel like this post needs a tl;dr about the context removal, and we need to be much more explicit around the fact it's happening. Addons being enabled is one thing, but the build changes are pretty big, and we want to highlight the extension, and explain more how it works, I think?

[humitos]

I agree we can add a warning note, an extra paragraph with some bold text or similar alerting users about the build context changes. However, we don't want all users to go and blindly install the extension. I understand that a good tl;dr would be something like: "Read the Docs stopped adding extra context and manipulating configuration on Sphinx builds. If you are experimenting any issue after addons are enabled by default, read "How does it affect my projects?" section and try installing sphinx-build-compatibility"

On the other hand, I think going too deep technically on what exactly has changed, what are the exact variables that are not passed anymore, how to configure those variables by yourself, etc won't be valuable here and won't help most of the users and I think it will only confuse them more than help. They aren't already aware of those, and for those users needing them, the solution is just to install the Sphinx extension --we don't need to explain this on details to regular users.

[humitos]

I went ahead and added a TL;DR small section at the beginning of the post. Besides, I added a small chunk of Python code that explains how to setup the canonical URL if they are using a custom domain, plus the READTHEDOCS variable in the context.

[ericholscher]

Looks better. I'm fine not highlighting the context removal as much, but I do think it will break more than we think it will, especially with all the themes, etc. 👍

[humitos]

Thanks for the review.

I'm happy to come back an update the post with some feedback received once we enabled it for new projects. We can also write a "Migration guide" in our documentation with more technical details if needed. We can also create an issue in our repository that links to this post and pin it; so users find it immediately when they go to open an new one about a related problem.

I targeted this post for next Monday, but we can merge it before that date if we are already happy with it. Let me know.

[ericholscher]

Yea, I think making sure we have a few places where we're noting this is important. 👍 I'm fine shipping it on Monday.