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
Decouple themes from core functionality #3636
Comments
I've created a repo here... https://github.com/mkdocs/theme-readthedocs and given the @mkdocs/core team access to it. |
Also related... (And possibly others?) |
I've thought about this for a while now and currently see two options: OptionsOption 1 – Move business logic and
|
Thanks for the detailed suggestions @squidfunk. I think I like option 1 too. |
I like option 1 as well. I will note that the existing mkdocs-bootstrap and mkdocs-bootswatch themes depend on and inherit from the I will add one counterpoint to this. Moving the To be clear, I'm not saying I think we shouldn't move forward with this. However, we will want to give some consideration to those users who use MkDocs with the readthedocs service. |
Excellent observation that slipped my attention. When following option 1, we could have a transition period where we automatically install |
This approach?...
|
@tomchristie I'm not sure I follow. As I understand from what you write, you're proposing to follow what I described as Option 2: move both themes out. Have you considered the breaking changes that this might incur which I described in #3636 (comment), or do you have something in mind that mitigates this problem which I'm not currently seeing? 😅 Because, what's the point where you'd be removing the dependencies? IMHO, we'd only be deferring this problem, so if we decide to follow this approach, we should have a plan in place, including a deprecation period. We just had a case where it would be super helpful if we would've decoupled the themes from core, as removing jQuery from the |
A crossover of Option 2 and what @tomchristie suggested in #3636 (comment) Option 3 – Move everything out and convert
|
I'll clarify, I was aiming at Option 0... * "Yeah, I'm not sure if we should go to the park or the beach. Maybe let's get dressed and have some breakfast, and we can have a think about it while we're doing that." * careful readers will notice some differences between my suggestion and the simile used. hopefully it conveys the gist, tho. |
Unless we play with the presence/absence of specific packages after installation, another way to show deprecation warnings is to keep vendoring the theme during the transition period, and emit warnings when the vendored files are used (can be done from Python code loading the theme, or from the Jinja templates themselves if we inject a logger into the Jinja context). |
@pawamoy excellent idea – vendoring could be a viable deprecation path ✌️ @tomchristie Okay, let me try to interpret your beautiful prose 😅 It sounds like you're suggesting to move out the I tried to outline some options all with up- and downsides, in order to get some more eyes on this. That already paid off, as we found some further implications that would need to be considered. Only moving out IMHO, for the restructuring to be successful, how we cut should align with the vision of MkDocs that we and especially you see. In my opionion, we shouldn't just start for the sake of doing something. That's at least how I see it. |
Not sure what @tomchristie meant, but I suppose we can start copying (not moving) the ReadTheDocs theme into the new repository. This would allow us to start playing with deprecation messages (as mentioned in my comment above). |
Exacyl, yes... https://github.com/mkdocs/theme-readthedocs/ |
If we'd opt for vendoring, we'd end up with two themes with the same name, so we'd need to make sure that precedence works in our favor, similar to what I did for plugins in 4ea78da. I'm not sure whether this behavior is currently defined. |
Good point. Maybe the external package could use entry point metadata, while the vendored files would not. If we don't find the specified theme through regular logic, and the theme is "readthedocs", we load it from vendored files (and emit a warning). |
During the backlog grooming call we decided to move the ReadTheDocs theme out of core, in a separate repository, and as a separate installable Python package.
The text was updated successfully, but these errors were encountered: