Feature flag to make readthedocs theme default on MkDocs docs
#4802
Conversation
Historically, we were using `readthedocs` as default theme for MkDocs but in #4556 we decided to change it to get the same behavior when building locally than in Read the Docs. This commit adds a Feature flag to keep having the old behavior for some particular projects so we can add these project and do not break their documentation (change the theme without asking/reason).
Codecov Report
@@ Coverage Diff @@
## master #4802 +/- ##
==========================================
+ Coverage 76.22% 76.26% +0.03%
==========================================
Files 158 158
Lines 10025 10034 +9
Branches 1264 1267 +3
==========================================
+ Hits 7642 7652 +10
Misses 2039 2039
+ Partials 344 343 -1
|
| if self.project.has_feature(Feature.MKDOCS_THEME_RTD): | ||
| if 'theme' not in user_config: | ||
| # mkdocs<0.17 syntax | ||
| user_config['theme'] = self.DEFAULT_THEME_NAME |
There was a problem hiding this comment.
The thing I think @davidfischer got caught up on here is that this might not work/break when a user pins mkdocs>0.17. Can you confirm the user has a way to self-select out of our feature flag?
|
|
||
| operations = [ | ||
| migrations.RunPython(forward_add_feature, reverse_add_feature), | ||
| ] |
There was a problem hiding this comment.
If we're not doing anything like setting a default with the migration, then we don't actually need it for feature flags to work. I guess we'll have to manually add a feature flag on the commercial side?
There was a problem hiding this comment.
Well, the migration in this case only creates the Feature flag object in the database.
If we don't want that, the migration is useless and I can remove it. As you prefer.
There was a problem hiding this comment.
Yeah, this is not required for feature flags. It's only needed if we are setting a time-based default.
There was a problem hiding this comment.
I think things look correct, but some of the logic might need to be tuned. I'll defer to @davidfischer as he probably has more background into if this will work for our current case and for users that pin mkdocs>0.17.
| # README: historically, the default theme was ``readthedocs`` but in | ||
| # https://github.com/rtfd/readthedocs.org/pull/4556 we change it to | ||
| # ``mkdocs`` to maintain the same behavior in Read the Docs than | ||
| # building locally. Although, we can't apply the this into the Corporate |
|
Why the default will never be used? Because it's mandatory to be a dict like |
This is all correct. In 1.0+, theme.name is mandatory. Nobody is using 1.0+ unless they specify it in their requirements file. |
There was a problem hiding this comment.
Looks good. I ran a quick test with the test project with no theme specified.
|
Great, sounds like this can be merged and hotfixed on our release branch. |
Historically, we were using
readthedocsas default theme for MkDocs but in #4556 we decided to change it to get the same behavior when building locally than in Read the Docs.This commit adds a Feature flag to keep having the old behavior for some particular projects so we can add these project and do not break their documentation (change the theme without asking/reason).