search

readthedocs / website

The Read the Docs community website
15 stars 6 forks source link

Post: enable addons by default #308

Closed humitos closed 4 months ago

humitos commented 4 months ago

Follows the plan we described in: https://github.com/readthedocs/addons/issues/72#issuecomment-2200390705

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

humitos commented 4 months ago

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 commented 4 months ago

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.

humitos commented 4 months ago

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 commented 4 months ago

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