-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Design doc: magical builder maintainability and builder expanding API #8215
Conversation
Design document to discuss how to make the "magical" builder maintainable over time and also how to extend the builder process to support other doctools eventually.
Besides, it removes the needing of using ``build.builder: 2`` since the *new builder* will extend the "magical" builder behavior | ||
and just override what's required. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought I had this idea clear in my mind when I started writing this, but then I realized that I didn't have a good and clear way as a user to disable all the magic. This may be a good topic to cover in our meeting.
We talked through this design document and some of these ideas today on a call. The main takeaway we had is that this isn't as straight forward as we were considering, but versioning our builder would be an incredibly useful first step to changing builder logic. GoalsTo distill down some higher level points:
Versioned buildersWe are discussing versioning builders as a first step to this work. This would allow us to make incremental, backwards incompatible changes to builder logic without negatively affecting users. We poked holes in our plan for versioned builders and came to the following conclusions:
The plan in this design doc to create a magic Sphinx builder and a separate non-magic Sphinx builder still stands. Without versioning figured out, we don't know how this looks technically. Changes to other stepsUsing the Sphinx builder as an example, we thought through how we might alter the build steps. I believe we came to the following conclusions:
We did not list "remove magic" as a goal of this work, because a good deal of the magic that helps the build process also provides really good UX to a lot of users. "Remove magic" is also maybe misleading, because we can't make the RTD build process match the local build process without dropping features like our flyout, search, etc. So, in this scenario, we are mostly keeping the current Sphinx builder code, instead of our plan to throw away all of this functionality in search of a build process that we don't control. Priorities and potential next stepsThe priority order for work likely looks something like this:
|
I admit I don't have knowledge of the architecture, but here are a couple of questions:
|
We are in a lot better situation now. We've removed a lot of the magic and we are migrating all our projects to addons (see readthedocs/website#308) The only relevant part from this document is the ability from the community to "package a builder" --but we've discussed we don't want to implement something custom and, if we are going to in that direction, using buildpacks or support running GitHub actions in our builders would be the path we would follow somehow. It's also worth noting the "magic" part of our build process, was migrated to a Sphinx extension in case people want to keep the old/magical behavior for some reason: https://github.com/readthedocs/sphinx-build-compatibility/ |
Design document to discuss how to make the "magical" builder maintainable over
time and also how to extend the builder process to support other doctools eventually.
Rendered version: https://docs--8215.org.readthedocs.build/en/8215/development/design/builder-maintainability.html